Audience data — batch file integration

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. 

The integration process consists in the following steps:

• the provider signs a data provider agreement with Equativ
• the provider sets up the user synchronization with Equativ and hosts a matching table (see Audience data — user synchronization)
• the provider sends the GCP service account email to Equativ; this is required to grant access to the appropriate bucket(s)
• Equativ provides credentials to the GCP service to access the taxonomy importer bucket and the profile importer bucket
• the provider uploads the list of their segments to the taxonomy bucket
• the provider feeds the segments with profiles (UserIDs) by uploading csv files to the profile bucket
• the segments are displayed in Equativ’s platform
• Equativ’s customers can 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 – more details here.

General bucket and folder structure

You will get access to 4 GCP buckets:

• 1 bucket to drop your taxonomy files
• 3 buckets to drop your userID files for each geographical region

Each GCP bucket contains one or multiple folders to drop your files.

The 4 GCP buckets will be duplicated for development (sandbox) and production environments:

• sandbox buckets 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 to be used for production data with the capacity to ingest up to 10GB per day for each dedicated folder

Get back to Equativ’s partner integration team if you are managing data for multiple Equativ customers and need to limit data access to segment taxonomies/profiles accordingly. In each bucket, you will get dedicated folders (with dedicated folder Ids) for each Equativ customer. 

Managing the segment taxonomy

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

Taxonomy buckets and folders

You get access to the following taxonomy buckets:

• taxonomy_importer_audience_sandbox for sandbox
• taxonomy_importer_audience_prod for production

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

Get back to Equativ’s partner integration team if you are managing data for multiple Equativ customers. In each taxonomy bucket, you will get dedicated folders (with dedicated folder Ids) for each Equativ customer. 

Creating the 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 do not want to fill an optional field, add the left and right separators as usual and leave the space empty (see example below); in any case, the order and structure must be preserved

Field (column)__	Data type	Default value	Description
SegmentId*	string (max. 200)		the data provider’s own SegmentId
ParentSegmentId	string (max. 200)	null	used to build the hierarchy of segments in the UI null: the segment is on the highest category level (it has no parent segment) not null: the parent SegmentId of which this segment is the child
Name*	string (max. 200)		the name of the segment
Description	string (max. 255)	null	a short description of the segment
Price*	float	0	the price of the segment; use 0 if you do not want to apply a price to the segment
IsSelectable*	boolean	1	indicates if the segment is targetable or just declared to build the hierarchy 0: the segment is not targetable - it is only declared to build the hierarchy 1: the segment is targetable
TTL*	int	43200	the time to live of the association between the userID and the segment (in minutes).
IsActive*	boolean	1	determines if the segment is active; used to disable a segment and thus remove it from targeting.  0: the segment is deactivated 1: the segment is active

* Mandatory fields; if a mandatory field is missing, the segment will be discarded!

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

Reminder: make sure your file is dropped in the right bucket, and under the folder ID of the appropriate Equativ customer.

The example below shows a csv file with the column headers and one row. Note that the ParentSegmentId is missing (null), i. e. this segment is on the highest category level (it has no parent segment)
 

Updating the segment taxonomy

To update segment information (e. g. name, price, etc.), drop a new file with updated information to the GCP folder in the taxonomy importer bucket.

The updated segment must have the same SegmentId and include all the information associated with the segment. It is not sufficient to include only the information that needs to be updated! If you do not provide all the information associated with the segment, the previous information will be lost.

Do not use the same SegmentId for multiple segments in the same file. If you do, Equativ will only import the latest segment from the uploaded file.

To delete (wipe out) a segment, please 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

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

Feeding profiles

Profile buckets and folders

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

You get access to the following profile buckets: 

• Development profile buckets
  • profile_importer_audience_us_sandbox for users located in the US
  • profile_importer_audience_eu_sandbox for users located in EU
  • profile_importer_audience_apac_sandbox for users located in APAC
• Production profile buckets
  • profile_importer_audience_us_prod  for users located in the US
  • profile_importer_audience_eu_prod for users located in EU
  • profile_importer_audience_apac_prod for users located in APAC

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.

Get back to Equativ’s partner integration team if you are managing data for multiple Equativ customers. In each profile bucket, you will get dedicated folders (with dedicated folder Ids) for each Equativ customer.

Associating 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 (columns) 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

Field (column)_______	Data type	Description
UserID	string	the identifier of the user; UserIDs are case sensitive and UTF-8 encoded; Equativ supports any ID type, e. g.: Equativ's cookie ID (to initiate a cookie sync with Equativ, as explained in Audience data — user synchronization ) mobile advertising ID (MAID) publisher provided ID alternative ID (extended ID); per folder, one alternative Id of one vendor can be set; if you need alternative IDs of multiple vendors, get back to Equativ’s partner integration team to get a dedicated folder for each of them IP address; frequently used to target Connected TVs or to match users with households; IP address formats must follow the standards; overlapping or truncated IPs will be ignored and not processed (e.g. IPv4 translated to IPv6 as ::ffff:202.124.87.3)
SegmentToSet	array	list of SegmentIDs to be associated with the UserID; separated by a comma; if the UserID already exists, all previously associated SegmentIDs are removed and replaced by the ones defined in column SegmentToSet
SegmentToAdd	array	list of SegmentIDs to be added to the UserID; separated by a comma; any previously associated SegmentIDs remain unchanged
SegmentToRemove	array	list of SegmentIDs to be removed from the UserID; separated by a comma; other, previously associated SegmentIDs remain associated with the UserID

Csv file example
To delete (wipe out) a segment, please 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 - or
• drop a new file with all profiles and segments but without the one to be deleted

Time to live of UserIDs

A UserID has a time to live of 14 days. If the UserID is not refreshed after 14 days, all the segments associated with it will stop being available for targeting.
As explained in section “Creating the segment taxonomy” above, you can also define a time to live for the association between a UserID and a segment. If the UserID-segment-association expires before the time to live of the UserID, the segment will be removed from the user even before the time to live of the UserID is over.