Overview

Semantic contextual data providers can sync semantic data 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 segment integration consists in the following steps:

• the provider signs a data provider agreement with Equativ
• 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
  • URL/BundleID importer bucket for URLs and apps (in separate folders);
• the provider uploads the list of their segments to the taxonomy bucket
• the provider feeds the segments with URLs/BundleIDs by uploading csv files to the URL/BundleID buckets
• the segments are displayed in EMP
• Equativ customers can target insertions or deals to the provider’s segments

Alternative API integration

As an alternative to the batch file integration described in this article, data providers can also use Equativ’s API integration method to sync contextual segments – more details here. 

General bucket and folder structure

You will have access to 2 GCP buckets to drop your taxonomy files and URL/BundleID files. The 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/categorized content 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 URLs or BundleIDs that share a common characteristic. A URL or BundleID can be associated with one or multiple segments.

Taxonomy buckets and folders

You get access to the following taxonomy buckets:

• taxonomy_importer_semantic_prod for production
• taxonomy_importer_semantic_sandbox for sandbox

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

* Mandatory fields; if a mandatory field is missing, the segment will be discarded! ** Available values for categorizationID (reach out to Equativ's partner integration team if you need additional categories not mentioned in the table below):  

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.

SegmentId|Name|Description|Price|ParentSegmentId|categorizationID|IsSelectable|IsExclusion|IsActive
123|Sport||0|||1|0|1  

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 URLs/BundleIDs

URL/BundleID buckets and folders

You get access to the following URL/BundleID buckets: 

• categorization_importer_semantic_prod for production
• categorization_importer_semantic_sandbox for sandbox

Within the URL/BundleID bucket, you will get access to a folder with two subfolders:

• url subfolder – to drop segments associated to URLs
• bundle subfolder – to drop segments associated to BundleIDs

Get back to Equativ's partner integration team if you are managing data for multiple Equativ customers. In each URL/BundleID bucket, you will get dedicated folders for each Equativ customer.

Associating URLs with segments

To associate URLs with segments, upload a csv file following the rules below:

• add one line per URL 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 associated with the URL and will not be available for targeting

Csv file example

URL|SegmentToSet|SegmentToAdd|SegmentToRemove mywebsite1.com/mypage.html|123|| mywebsite2.com/mypage.html||123,456| mywebsite3.com/mypage.html|789,101|| mywebsite4.com/mypage.html||111,112|113,114

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 URLs and segments but without the one to be deleted

Time to live of URLs

A URL has a time to live of 7 days. If the URL is not refreshed after 7 days, all the segments associated with it will stop being available for targeting.

Associating BundleIDs with segments

To associate BundleIDs with segments, upload a csv file following the rules below:

• add one line per BundleID 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 associated with the BundleID and will not be available for targeting

csv file example

BundleID|SegmentToSet|SegmentToAdd|SegmentToRemove com.myapp1.android.webmail|123|| com.myapp2.android.webmail||123,456| 294047850|789,101|| 274645857||111,112|113,114

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 BundleIDs and segments but without the one to be deleted

Time to live of BundleIDs

A BundleID has a time to live of 7 days. If the BundleID is not refreshed after 7 days, all the segments associated with it will stop being available for targeting.