In this article

A guide intended for publishers and marketers who want to upload audience segments into Permutive. This is typically user segment membership data that is non-endemic to Permutive, such as CDP subscriptions, event sign-ups, data providers, or other identifiable users.

The data import can be a one-off data dump or a periodic import.

Overview

Audience Imports consist of three main components: overarching definition of the import, definition of the taxonomy, and the actual user data files. 

Currently, there are only two sources of user data that are supported: LiveRamp and Google Cloud Storage (GCS). The following document outlines the steps for GCS Import. Please follow this article for LiveRamp Imports. 

Step 1: Create Import

Note: If the Imports tool is not enabled for your workspace, please reach out to your customer support team. 

1. Navigate to the Permutive Dashboard
2. On the left-hand menu, you will see Imports, under Audiences
3. On the Imports page, Click the 'Create New Import' button
4. Follow all steps and create your new Import                                                                                       
   1. Import Name: Use a name that differentiates the user segments from other groups of segments.
      1. 1. For example, this can be a data partner or platform's name, where the data is being sent from like the CDPName_Demographics or Bombora_US.
   2. Upload Access Accounts: These accounts will upload data into the GCS file path. Ensure the right Google account types have been given access to upload. This is critical for step 3, methods for uploading data files.  
   3. Read Access Accounts: This is not mandatory. These accounts will be able to read the data files in the GCS file path. Ensure the right Google account types have been given access to upload. 
   4. Data Provider Lifetime (days): Each import lifetime will default to 60 days. Lifetime is set to all segments in the import.
      1. 1. To change this after creating the import please reach out to Permutive Support.

Here is a quick video on creating a new import!

Step 2: Set Taxonomy

Tip: Each Import will have it's own taxonomy. The taxonomy matches segment names to the segment codes in the data files, which does not contain names - just codes. This is a privacy measure to ensure the segment codes are only understood in the permutive platform, not externally. The segments are legible when creating custom cohorts in the Permutive Dashboard. 

1. Navigate to Imports and click the specific import you would like to update
2. Click 'Download Taxonomy' to download the template for the taxonomy (if no taxonomy is set) or the latest taxonomy.                               

   Note: Every upload to the taxonomy is a full update, so the upload must contain the definition as you want it set. There are no incremental updates

3. Update the taxonomy on your desktop and save it as a .csv file
4. Navigate back to the Dashboard, select 'Upload Taxonomy' 
5. Select your file, review the changes, and update.

Please see our article on Taxonomy Field Definitions 

Note: There is a Taxonomy API available, which can set, create and delete segments. This can be found here.

Step 3: Uploading Data Files 

Note: When setting up the import (Step 1), certain account types were given upload access. We will outline the typical processes for the two methods of data file uploads below, after the file requirements. 

File Requirements

The file must be a tab-separated file. For efficiency, data files should be uploaded in compressed format. Please gzip and compress your files prior to uploading. Post compression, file names should end with a ".gz" extension.  If the files end with a ".gzip" extension, the import will not work.

Each row in your file should describe a list of segments for a specific user. The row must be in the following format:

<USER ID><TAB><SEGMENT CODES COMMA SEPARATED>

For example, an import of four segments against a user ID would appear as a single row in the data file, with a comma-separated list of segments codes:

5fc96027e15 0001,0003,0006,0005

Please see the Data File Format tab in the section below, for more details

1. Manual file upload 

Access: Upload access has been given to Google Workspace group email addresses or user google email account access to the import. The account has to be recognized as associated with an active Google Account or Google Apps account. Using group email accounts allows you to manage user access, meaning if you want to add/remove users you do not need to reach out to us.

Suggested method: You can upload files via the Google Cloud Platform Console or command-line tool. 

https://console.cloud.google.com/storage/browser/<insert file path>*

*This can be found on the information tab of the Import. Be sure to copy text after gs://

2. Programmatic file upload 

Access: Upload access has been given to a service account within your GCP project, which will be used to perform uploads to Permutive.

Limits

To ensure seamless data ingestion, we impose some system limits for each file upload. If you think you will need to exceed these limits, please let us know.

Creating Cohorts with Audience Import Segments

Once our support team has confirmed the cohorts are available:

1. Navigate to the 'Audience' > 'Custom Cohorts' tab in the Permutive dashboard

2. Select '+ Add Cohort'

4. Set up any first-party rules

5. Choose '+OR/+AND' and then 'Audience imports'

6. Search for and select the relevant audience segment

7. Save the cohort