Overview 

With Equativ’s batch file integration method, audience data providers can sync segments and profiles with Equativ through file uploads in cloud storage buckets. Since Equativ uses Google Cloud Platform (GCP), a Google account is required to get access to Equativ’s GCP buckets. 

Here are the integration steps:

1. The provider signs a data provider agreement with Equativ.
2. The provider sets up the user synchronization with Equativ and hosts a matching table. For more information, see Sync user.
3. The provider sends the GCP service account email to Equativ, required to grant access to the appropriate buckets.
4. Equativ provides credentials to the GCP service to access the taxonomy importer bucket and the profile importer bucket.
5. The provider uploads the list of their segments to the taxonomy bucket.
6. The provider feeds the segments with profiles (UserIDs) by uploading csv files to the profile bucket.
7. The segments are displayed in Equativ’s platform.
8. Equativ’s customers target insertions or deals to the provider’s segments.

About the API integration of audience data

As an alternative to the batch file integration described in this article, data providers can also use Equativ’s API integration method to sync audience data. For more information, see Sync segments and profiles (API v2).

General bucket and folder structure

You will get access to the following four GCP buckets:

• One bucket to drop your taxonomy files.
• Three buckets to drop your userID files for each geographical region.

Each GCP bucket contains one or multiple folders to drop your files. The four GCP buckets will be duplicated for development (sandbox) and production environments:

• Sandbox buckets: Used to test if the file format is properly supported and if data is properly ingested in Equativ’s systems. These buckets are meant to receive a limited amount of data.
• Production buckets: Used for production data with the capacity to ingest up to 10GB per day for each dedicated folder.

Manage the segment taxonomy

A segment represents a pool of users that share a common characteristic, such as a location, demography, interest, or purchase intent. A UserID can be associated with one or multiple segments.

Taxonomy buckets and folders

You get access to the following taxonomy buckets:

• Sandbox bucket: taxonomy_importer_audience_sandbox
• Production bucket: taxonomy_importer_audience_prod

Each bucket contains dedicated folders with dedicated folder IDs where you will drop your taxonomy files.

Create segment taxonomy

To create your segment taxonomy, upload a csv file following the rules below:

• Add one line per segment with the fields (columns) specified in the table below.
• Separate the values (and column headers) by a pipe character (“|”).
• Column headers are optional and will not break the import if included.
• The price currency is defined for each account/folder.
• If you don't want to fill an optional field, add the left and right separators as usual and leave the space empty, as shown in the example. In any case, the order and structure must be preserved.

As soon as the file is dropped to the folder in the bucket, it will be processed and segments will be created.

Mandatory fields

Optional fields

Example

SegmentId|ParentSegmentId|Name|Description|Price|IsSelectable|TTL|IsActive|RelativePrice|MetaSegmentIds
123||Gender: Male||0.50|1|24000|1||
124||Automotive intenders||1.20|1|43200|1|0.15|eumm_automotive
125||Food lovers|||1|43200|1|0.10|eumm_food,eumm_lifestyle
126||Sports fans||0.80|1|43200|1||-1

• The header row is present only to explain each column. It is optional.
• If you fill in MetaSegmentIds but not RelativePrice, leave the 9th column empty (||).
• All segments are on the highest category level. They have no parent segment as the ParentSegmentId is missing (null). 
• Row 123 uses a flat price only and has no meta segment.
• Row 124 uses both prices and belongs to one meta segment.
• Row 125 uses a relative price only and belongs to two meta segments.
• Row 126 removes all meta segment mappings of the segment.

Price segments

You can price a segment in the following three ways:

• Flat price only: Set Price and leave RelativePrice empty. The segment costs this CPM.
• Relative price only: Set RelativePrice and leave Price empty. The segment costs this share of the media price of the deal.
• Both flat price and relative price: The relative price is applied, capped at the flat price.

A row is rejected if RelativePrice is lower than 0, equal to or above 1, or uses a comma as the decimal separator.

Map segments to meta segments

A meta segment groups segments from several data providers under one targetable segment, for example in a media marketplace, such as the European Media Marketplace.

Follow these guidelines to manage meta segment mappings:

• Set or change a mapping: List the meta segment IDs in MetaSegmentIds. The list replaces any mapping sent before for this segment.
• Keep the current mapping: Leave MetaSegmentIds empty, or send only the first 8 columns (without RelativePrice and MetaSegmentIds). This is an exception to the rule that each import replaces all information about the segment.
• Remove all mappings: set MetaSegmentIds to -1. -1 must be the only value in the column. Don't combine it with meta segment IDs.
• Unknown meta segment ID, or account not enabled: The segment is still imported, but the mapping is not applied. Contact your account manager if a mapping doesn't appear.

Update segment taxonomy

To update segment information, drop a new file with updated information to the GCP folder in the taxonomy importer bucket, following these guidelines:

1. Re-use the existing SegmentId when updating a segment, and ensure to include all current segment data. Omitted fields will be erased, as updates replace the entire segment record rather than making partial changes.
2. Don't use the same SegmentId for multiple segments in the same file. If you do, only the latest segment from the uploaded file is imported.
3. To delete a segment, contact Equativ’s partner integration team. Alternatively, you can update the taxonomy file by changing the isActive field to false to remove the segment from targeting.

Known limitations

Equativ is not able to manage segment names or descriptions in multiple languages.

Feed profiles

Profile buckets and folders

Profiles are end-users (UserIDs) associated with segments.

You get access to the following profile buckets: 

• Sandbox profile buckets
  • Users located in US: profile_importer_audience_us_sandbox 
  • Users located in EU: profile_importer_audience_eu_sandbox
  • Users located in APAC: profile_importer_audience_apac_sandbox 
• Production profile buckets
  • Users located in US: profile_importer_audience_us_prod
  • Users located in EU: profile_importer_audience_eu_prod
  • Users located in APAC: profile_importer_audience_apac_prod

Profile buckets are organized by geographical regions. Therefore, it is critical to drop the users to the appropriate buckets (US, EU, APAC). If users located in a given region are pushed to the wrong geographical bucket, data will not be available for targeting.

Each profile bucket contains dedicated folders with dedicated folder IDs where you will drop your profile files.

Associate profiles with segments

To associate profiles (UserIDs) with segments, upload a csv file following the rules below:

• Add one line per profile (UserID) with the fields specified in the table below.
• Separate the columns by a pipe character (|).
• Separate SegmentIDs by a comma (,).
• Column headers are optional and will not break the import if included.
• The SegmentIDs must be the same as the ones provided in the taxonomy file. If the SegmentID has not been pushed previously through a taxonomy file, this SegmentID will not be available for targeting.

Csv file example (without profileIdSource)

UserID|SegmentToSet|SegmentToAdd|SegmentToRemove
glVQoCkEgJcWya7NrUYac|123||
ll1iA1FJMNDYGUHZef_3WCIMpc9e||123,456|
HtxdBDwK8OC-fV4sE|789,101||
nwGPW6UZeX4Esgcrz2_TbU87L||111,112|113,114

Csv file example (with profileIdSource)

UserID|SegmentToSet|SegmentToAdd|SegmentToRemove|ProfileIdSource
user-001|12345,12346||67890|crm_sourceid123
user-002||45678|98765|crm_sourceid456
user-003|11111,22222|||

If a row leaves the ProfileIdSource empty, it is treated as absent. 

Delete segments

To delete a segment, please contact Equativ’s partner integration team or choose one of these options:

• Update the taxonomy file by changing the isActive field to false to remove the segment from targeting.
• Drop a new file with all profiles and segments but without the one to be deleted.

Unencrypted alternative IDs (eids)

Upload a csv file containing unencrypted alternative IDs (eids) under the following path:

Production profile bucket > Data provider name > Segment provider ID > Csv file

The following list explains each item within the path:  

• Production profile bucket: The bucket depends on the geographical region of the users, for example: profile_importer_audience_eu_prod. For the full list, see section “Profile buckets and folders", earlier in this document.
• Data provider name: The name of the data provider.
• Segment provider ID: A unique identifier provided by Equativ's tech ops team, representing a specific account for a DMP or data provider.
• Csv file: The csv file.

The following is an example of a csv file containing unencrypted alternative IDs, uploaded into the appropriate folder in an EU production profile bucket:

profile_importer_audience_eu_prod/data_provider_name/abc28132y484ry24givncdkmn/filename_unencrypted_eids.csv

Encrypted alternative IDs (eids)

Equativ can process encrypted alternative IDs (eids) from the providers Utiq and ID5 without prior decryption. Equativ manages the decryption process internally using the respective provider's APIs.

To enable Equativ to perform this decryption, you must upload the csv file containing the encrypted IDs under the following path:

Production profile bucket > Data provider name > Segment provider ID > extendedIds > Eid provider domain > Csv file

The following list explains each item within the path:  

• Production profile bucket: The bucket depends on the geographical region of the users, for example: profile_importer_audience_eu_prod. For the full list, see section “Profile buckets and folders", earlier in this document.
• Data provider name: The name of the data provider.
• Segment provider ID: A unique identifier provided by Equativ's tech ops team, representing a specific account for a DMP or data provider.
• extendedIds: A static item of the path. Do not change.
• Eid provider domain: The domain of the encrypted eid provider. Either utiq.com or id5-sync.com.
• Csv file: The csv file.

The following is an example of a csv file containing encrypted Utiq IDs, uploaded into the appropriate folder in an EU production profile bucket:

profile_importer_audience_eu_prod/data_provider_name/abc28132y484ry24givncdkmn/extendedIds/utiq.com/filename_encrypted_eids.csv

Time to live of UserIDs

A UserID has a 14-day Time to Live (TTL). If a UserID isn't refreshed within 14 days, all associated segments become unavailable for targeting.

As detailed in "Create segment taxonomy", individual UserID-to-segment associations can also have their own TTL. If an association expires before the UserID itself, that segment is removed immediately without waiting for the full 14-day UserID lifecycle to end.