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 of 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 buckets.
• Equativ provides credentials to the GCP service to access the following buckets:
  • 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/ContentIDs by uploading csv files to the URL/BundleID buckets.
• The segments are displayed in the Monetization platform.
• 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. For more information, see Sync contextual segments (API integration).

General bucket and folder structure

You get access to GCP buckets to drop your taxonomy files and URL, BundleID, and ContentID files. The buckets are duplicated for development (sandbox) and production environments:

• Sandbox buckets: This bucket is 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: This bucket is 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. 

Manage the segment taxonomy

A segment represents a pool of URLs, BundleIDs, or ContentIDs that share a common characteristic. A URL, BundleID, or ContentID 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.

Create segment taxonomy

To create your segment taxonomy, upload a csv file:

• 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 is 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 following example 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  

Update segment taxonomy

To update segment information, 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 a segment, reach out to Equativ's partner integration team. Alternatively, you can update the taxonomy file by changing the isActive field to 0 to remove the segment from targeting.

Known limitations

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

Feed URLs, BundleIDs, and ContentIDs

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 with URLs.
• bundle subfolder to drop segments associated with BundleIDs. ⚠️ Warning: ContentIDs don't have a dedicated subfolder. They must be dropped into the bundle subfolder and are not accepted in the url subfolder.  

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.

Associate URLs, BundleIDs, and ContentIDs with segments

To associate URLs, BundleIDs, or ContentIDs with segments, upload a csv file containing either URLs, BundleIDs, or ContentIDs:

• Add one line per URL, BundleID, or ContentID 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, BundleID, or ContentID and will not be available for targeting.

 * The csv file can contain either URLs, BundleIDs, or ContentIDs. Csv files containing ContentIDs must be dropped in the bundle subfolder.

Time to live

A URL, Bundle ID, or ContentID has a time to live of 7 days. If it isn't refreshed after 7 days, all the segments associated with it stop being available for targeting.

Delete segment

To delete a segment, reach out to Equativ's partner integration team. Alternatively, you can 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 URLs, BundleIDs, or ContentIDs and segments without the one to be deleted.

URL 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

BundleID 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

ContentID csv file example

contentId|SegmentToSet|SegmentToAdd|SegmentToRemove
content_12345|123||
content_67890||456,789|