The Category Definition File (CDF) is used to define the category structure and display names for category IDs that you send through tags.

The Category Definition File maps every category ID sent in tags to a display name and parent category. The file should be uploaded to Digital Analytics through Import on the Tools menu (Import the Category Definition File) or the SFTP account that is configured and managed through the GUI. The CDF allows you to update the existing category hierarchy without modification of the tag implementation site code. Updated or rearranged category organization can be created in the reporting through modification of the CDF. This simplifies the management of the reporting hierarchy.

To find out more about CDF, visit our Acoustic Academy course on data collection.

Category Definition File Format

The Category Definition File is a comma-separated values file (CSV). Each line describes a category in the hierarchy. Each line has four values:

• Client ID
• Category ID
• Category Name
• Parent Category ID

Column	Description
Client ID	Digital Analytics assigned ID. This value should be the same for all rows within a given file.
Category ID	Category ID for the category being defined. This value should match the values being sent in the Digital Analytics tags or referenced in the Parent Category ID column of the CDF.
Category Name	The display name that should be used for this category ID in reporting.
Parent Category ID	The Category ID of this category's parent category. For top-level categories, this column should be empty.

Every category ID that is sent through the Digital Analytics tags on your site or referenced in the Parent Category ID column should have a matching line within the CDF that maps the ID to a display name and parent category. Category IDs that do not have a matching line within the CDF will be grouped into the "No Category Assigned" top-level category in reports.

The Digital Analytics TagBar can be used to identify what category ID is being sent in a tag. The Category ID (cg) field displayed in the TagBar output should match a Category ID in the second column of the CDF for that Client ID.

Invalid characters

Single quotation marks (') and double quotation marks (") are automatically removed from collected tag Category ID parameter values. Thus, no tag data can be assigned to Category IDs that contain quotation marks. However, single and double quotation marks can be included in Category Name column values for report display purposes. Following is an example:

99999999,204,DRILL BITS 1/4" TITANIUM,202

Commas (,) found in Category ID or Parent Category ID column values are replaced with spaces (" ") during loading of the category records. This ensures that tags sent with Category ID (cg) parameter values including commas will match the loaded Category Definition File record.

Multibyte CDF characters

Only single-byte data should be included in the CDF supporting a single byte-enabled Client ID. Single byte-enabled Client IDs cannot include categories with multibyte characters; such categories will not be available in reporting.

CDF column data (Category ID, Name, and Parent) for multibyte-enabled Client IDs can include multibyte characters.

Example of Category Definition File

The following example shows the category structure with corresponding records.

Category ID, Category Name, and Parent Category columns (2-4) values can be in uppercase, lowercase, or mixed case for character sets having multiple case values. All CDF column values are converted to uppercase upon import to Digital Analytics (ftp.digitalanalytics-eu-1.goacoustic.com or ftp.digitalanalytics-us-1.goacoustic.com). All collected tag Category ID values are also converted to uppercase after receipt of the tag by Digital Analytics, so the Category ID values in columns 2 and 4 of the CDF will always match the same Category ID value collected in tag data.

Client ID	Category ID	Category Name	Parent Category ID
99999999	101	MENS
99999999	201	WOMENS
99999999	301	SALE
99999999	102	MENS SHIRTS	101
99999999	103	MENS PANTS	101
99999999	104	MENS SHIRTS: DRESS	102
99999999	105	MENS SHIRTS: TEE	102
99999999	202	WOMENS SHIRTS	201
99999999	203	WOMENS PANTS	201
99999999	204	WOMENS SHIRTS: DRESS	202
99999999	205	WOMENS SHIRTS: TEE	202
99999999	302	SALE: SHIRTS	301
99999999	303	SALE: BRANDS	301

Example file

99999999,101,MENS,
99999999,201,WOMENS,
99999999,301,SALE,
99999999,102,MENS SHIRTS,101
99999999,103,MENS PANTS,101
99999999,104,MENS SHIRTS:  DRESS,102
99999999,105,MENS SHIRTS:  TEE,102
99999999,202,WOMENS SHIRTS,201
99999999,203,WOMENS PANTS,201
99999999,204,WOMENS SHIRTS:  DRESS,202
99999999,205,WOMENS SHIRTS:  TEE,202
99999999,302,SALE: SHIRTS,301
99999999,303,SALE: BRANDS,301

Uploading the CDF

The CDF should be uploaded through the CDF import tool at Tools > Import (Import the Category Definition File). This tool allows direct uploads of CDFs through the user interface or creation of an SFTP (port 998) server account with Digital Analytics (ftp.digitalanalytics-us-1.goacoustic.com - US Data Center) for the scheduled upload of automatically generated CDFs.

Europe Data Center domains: ftp.digitalanalytics-eu-1.goacoustic.com

Files imported through the Import GUI or sent to ftp.digitalanalytics-eu-1.goacoustic.com or ftp.digitalanalytics-us-1.goacoustic.com will be automatically imported and processed, and your categorization hierarchy in reporting is updated from that point forward. Changes from an uploaded file should be reflected in the next processing of the daily reports. The frequency at which the CDF is uploaded can be determined based on your own needs. If your hierarchies might change on a daily or weekly basis, we recommend setting up an automated script that will generate the CDF and upload it daily. This ensures that Digital Analytics picks up any changes in the hierarchy on a daily basis.

If you have a new area of the site with new categories, you’ll want to include those new categories in the CDF to organize the report hierarchy for those new Products or Pages. However, sometimes you may see your upload has failed. In that case, contact Acoustic Support.

File Naming Convention

The CDF should be named according to the following convention:

CDF_<client_id>.csv where <client_id> is your Digital Analytics assigned client ID.

Categorizing site content and products

You can categorize your site content and products through a combination of Category IDs in your tag functions and the Category Definition File (CDF), an offline file upload.

There are two types of categorization within Digital Analytics: product categorization and page categorization. Product categorization is captured in the Product View, Shop Action 5, and Shop Action 9 tags and displayed in the Product Categories report. Page Category data is captured in the Page View and Technical Properties tags and displayed in the Page Categories report.

Category IDs are captured in the Page View, Product View, Shop Action 5, Shop Action 9, Technical Properties, and Error tags to assign a particular page or product-related action to a particular category. The Category ID specifies only the immediate leaf category that the action belongs to, and does not contain any sense of a larger hierarchy within it. The Category ID for a given product should be consistent across the Product View, Shop Action 5, and Shop Action 9 tags.

Product Categories Categorization Inheritance

To simplify the implementation of product tag categorization, Digital Analytics features server-side Category ID inheritance processing. This processing causes uncategorized Shop Action 5 and Shop Action 9 tags to be categorized according to other categorized Product View tags or Shop Action tags collected for the same product within the same data collection session. These rules are applied during the processing of daily report data.

Category inheritance at the time of report processing follows these rules:

Product View tags

Product view tags do not inherit categorization from other tags including other categorized Product View tags in the same session. Product View tags should always be collected with valid values in the Category ID parameter.

Shop Action 5

Shop Action 5 tags that are collected without a Category ID inherit the Category ID from another same-session Shop Action 5 tag having the same Product ID. If no matching Shop Action 5 tag with a categoryID is found in the session, inheritance devolves upon a matching Product View tag with a non-null Category ID.

Shop Action 9

Shop Action 9 tags that are collected without a Category ID inherit the categoryID from another same-session Shop Action 9 tag having the same Product ID. If no Shop Action 9 tag with a Category ID is found in the session for that Product ID, inheritance devolves upon the Shop Action 5 tag or Product View tag, in this order: 1) a matching Shop Action 5 with a non-null categoryID or 2) a matching Product View tag with a non-null Category ID.

Exceptions

In certain special cases, Digital Analytics categorization inheritance processing might not be able to achieve 100% complete categorization in Product Categories.

Persistent Carts

Visitors viewing a saved cart in a new session, and/or completing a purchase might not view product detail pages, resulting in a lack of a categorized Product View tag for the Shop Action tags to inherit categorization from. In this case, a valid Category ID parameter value should be included with the Shop Action 5 tags sent when the persisted cart is retrieved and viewed. Shop Action 9 tags inherit categorization from the Shop Action 5 tags and need not be categorized.

Direct add-to-cart Site Functionality

This site functionality typically allows visitors to bypass the product detail page and associated Product View tag data collection by adding items directly to the cart from product category display pages. If no Category ID value is sent with a Shop Action 5 tag, this tag and any subsequent Shop Action 9 tags for this Product ID is uncategorized in reporting due to lack of a categorized Product View tag in the session. In this case, a valid Category ID parameter value should be included with the individual Shop Action 5 tag sent when the add-to-cart event occurs.