User-Data Onboarding by CSV

To use this method, prepare and maintain a CSV file with unique user IDs and additional data, and upload it nightly (recommended). When the data is uploaded, it's synced with Experience OS audience conditions according to a JSON schema you'll prepare for this purpose. Later, you can create audiences using these targeting conditions, and when users visit your site and are identified, they are automatically included in the audience if they meet the defined conditions.

Onboarding overview

The onboarding process includes the following steps: 

• Step 1: Prepare the file and folder: Do this before initiating the process in Experience OS. 
• Step 2: Prepare the schema: You can prepare the schema before starting the onboarding process, or do it in the order described here.
• Step 3: Determine a common identifier: Decide which identifier to use in advance; define the identifier and other file attributes during the onboarding process.
• Step 4: Upload the data: Upload, validate, and save.

Before you start, note that some steps might require your technical team.

Step 1: Prepare the file 

Use the following guidelines:

• File type: CSV  

• File format: UTF-8 encoded. If using non-Latin characters (Russian, Japanese, and so on), use UTF-8 with BOM.

• Filename: CRM_data.csv
• Columns:
  The first column is the identifier and is mandatory. This can be the CUID or an external ID.  Learn more about selecting an identifier in the next section, Determining the common identifier.
  Additional columns are any attributes that are meaningful to your business. You can add up to 1,500 columns.
  Note: For privacy reasons, do not include any attributes that are considered PII (such as name, date of birth, address, and so on).
• Attribute formats: You can use the following attribute formats in the file:

• File size: Up to 100 MB. If your file exceeds this limit, see Large file handling later in this article.

Sample CSV file

Download this file

Determining the common identifier

Each user record must include a unique identifier, to match between an online user and the attributes you defined in your feed. We recommend using email addresses (SHA256 hash of a lowercase email address). For privacy reasons, do not use plain text PII (such as name, phone number, or email address) as the identifier.

Make sure that all the identification events, including Identify, Login, Signup, and Newsletter Subscription use the same identifier.

Step 2: Create a new feed and request credentials

1. Navigate to Assets › Data Feeds, and then click New.
2. On the Choose Type page, select User Data. The Edit User Data page appears.
3. Enter a name for the feed. The name of your User Data feed will be the name of the audience condition you use later to create an audience. You can name the feed whatever you want.
4. Optionally, add notes or labels.
5. Select Upload a CSV file as your feed source, and then click Request Credentials to get credentials for an AWS S3 bucket. Copy and store the credentials for future reference. Make sure to save both the path and the key information. To send yourself the credentials by email, cliclk Email Credentials. 
    

Step 3: Create the schema

Use the User Data Schema Creator to create or modify your schema. The schema is JSON code that's used to sync the user data to a User Data feed in Experience OS. The schema takes the information in the CSV file and "translates" it into the corresponding condition types and operators in the audience creation process. The attributes you define in the schema then appear in your audience targeting conditions.

When you complete your schema in the schema creator tool, copy the code into the Data Schema field in the feed settings. 

Step 4: Set the identifier and other file information

In the fields under the schema editor, define the following parameters for your file:

If you have more than one Dynamic Yield section, you can add section names in the Allow targeting on field to use these targeting conditions on them as well. Note that this means that all data synced to this feed on Dynamic Yield is shared with the allowed sections listed here. Also, the feed can be edited only in the original section. 

Step 5: Upload the data 

To upload the CSV file, you must again go "off site", and access your designated S3 bucket. The path is the one generated in step 2, with your folder name, like this:

s3://com.dy-external.crm/Bucket_Id/Folder name (AWS US)
s3://eu-central-1.dy-external.crm/Bucket_Id/Folder name (AWS EU)
Example:
s3://com.dy-external.crm/ac24968c6c258114dac148ab/upload_2021-02-28_00-03

Make sure the folder that contains your upload file follows this name format: 
“upload_YYYY-MM-DD_HH-mm” (for example, upload_2021-02-28_00-03)

Now, go back to the Edit Data Feed page in Experience OS, and click Validate.

Preview your data, and if everything is as expected, click Save and Activate.

Now, the data is processed by Dynamic Yield. Upon completion, the relevant conditions appear in your Audience Manager. The targeting by audience conditions begins immediately, but reports can take up to 24 hours to process. 

Large file handling

The maximum supported file size is 100 MB. If your file is larger than 100 MB, split it into multiple files of about 40 MB, making sure the following is true:

• The structure of all the files is identical.
• The files don't duplicate users.

You'll upload the files to the same daily folder. The LAST file name must be CRM_data.csv (same as the single file standard upload described earlier). This is the file that triggers the ingestion of the data in the folder, which is why it must be added last. 

The other files can be named anything, though we recommend keeping a consistent naming scheme. For example: 

• CRM_data_part_1.csv

• CRM_data_part_2.csv

• CRM_data_part_3.csv

• ...

• CRM_data.csv (last file, triggers the ingestion)

Share user data between sections

After you set up the user data feed, you can share it across sections to enable the creation and targeting of Audiences based on user-data properties. This is especially useful when maneuvering between staging and production environments, or if your traffic migrates between multiple properties managed under the same Dynamic Yield account.

To enable data sharing, locate the Allow targeting on option after the data schema settings. By default, it is pre-populated with the name of the current section. If you want to share the data with an additional section, click the field and select the relevant section from the dropdown menu.

Note that after the data is shared, the feed can only be edited from the original section.

Create and review audiences based on user data

In the Audience Explorer, you can explore user segments and analyze their performance in comparison to your entire online user base, complemented by users' behavioral data captured by Dynamic Yield.

In the Audience Manager, the new conditions can be coupled with any other Dynamic Yield condition available in your account to create and save audiences, which in turn can be incorporated into your Dynamic Yield site personalization experiences and recommendations. 

Note: When you create an Audience with conditions that rely on data mapped as an array of strings (Text Array), the operators available are "is", "is not", "contains", and "does not contain", where "is" is met when any of the values in the array match the listed value, and "contains" is met when any of the values in the array contain the listed value.