You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 30 Next »

Data partner integration guide for audiences

Use this guide to integrate your audience segments with the PubMatic system.

Required before integration 

  1. Get PubMatic's  API Token:  provide PubMatic with the developer's First Name, Last Name, and Email Address to create an API authentication token.

    To learn more…

  2. Integration also requires a data partner ID (DPID).

Data integration

Data owners can send…

Cookie IDs for mobile and desktop/web, as well as IDFA/Android device IDs for mobile apps. However, each specific device type requires a unique DPID. You cannot interchange DPIDs between different Device Types.

For Mobile app IDFA/Android device IDs, step 1 below is NOT required, but step 2-3 remain the same.

Data integration requires three steps:

  1. Unique identifier (UID) sync.

  2. Segment registration.
  3. Data transfer.

Unique identifier (UID) sync

PubMatic can process data only from PubMatic User IDs…

To use data from other sources, a data provider must create a user-match table between PubMatic's user IDs and their own user IDs.

Steps for user sync-up:

  1. The data provider must provide PubMatic with an image pixel similar to, <img src="http://partner.com/xxxx?id=UID" width=1 height=1> .
  2. If data comes from a publisher, then PubMatic incorporates the image pixel from step 1 in a PubMatic pixel. The publisher must fire the PubMatic pixel across their website to maximize coverage across their users. Firing the pixel also lets the the data provider create the match-table. 
  3. If data comes from a buyer, PubMatic fires the image pixel from step 1 across PubMatic's site

Segment registration

Register segments ONLY ONCE before data transfer…

Perform registration only for any new segments you send.

Data providers must register new segments with source segment IDs before sending data to PubMatic. PubMatic ignores unrecognized segment IDs to avoid processing mistakenly sent data.

Two ways to register segments:

  1. Register segments with the Segment Registration APIs; see, Register an Audience segment, to learn more.)
  2. Bulk-register segments in the PubMatic system UI using the menus, Publisher Account > Audience > Audience Segment > Bulk Upload Segments:

Data transfer

Sent data to PubMatic using any of the following methods:

Server-to-server (S2S) data transfer

The server-to-server data transfer mechanism is a highly-efficient way to pass data to PubMatic because the data transfer happens directly between servers. The following diagram illustrates the server-to-server data transfer process between a data provider and PubMatic.

The process follows these steps:

  1. A user lands on a web page.
  2. PubMatic and a data provider receive the UID.
  3. PubMatic syncs with the data provider by sharing the data transfer API URL.
  4. The data partner passes the audience segment data to the PubMatic data transfer API in batches. The data transfer API typically requires the PubMatic-specific UID and the list of audience segment IDs as input.


For users whose audience profile changed since the last data transfer…

Data partners must transfer the updated audience profile information to PubMatic in batches.

Data transfer api format (server-to-server)

An example PubMatic data transfer API URL for server-to-server data transfer:

http://aud.pubmatic.com/AdServer/Artemis?dpid=[data_partner_ID_assigned_by_PubMatic_at_the_time_of_integration]
&userid=[PubMatic_User_ID]&segid=[comma_separated_list_of_segment_IDs]&ip=[last_known_user_IP_address]
&country=[country_code]&addseg=[comma_separated_list_of_segment_IDs_to_be_appended]
&remseg=[comma_separated_list_of_segment_IDs_to_be_removed]

Remember to replace placeholder values in the URL above with real data for each request:

  • [data_partner_ID_assigned_by_PubMatic_at_the_time_of_integration] - the data partner ID (DPID) PubMatic shares with the data partner at time of integration.
  • [PubMatic_User_ID] - replace with the PubMatic user ID; that is, the user ID passed to the data partner by PubMatic during the UID sync step.
  • [comma_separated_list_of_segment_IDs] - replace with a complete comma-separated list of all audience segment IDs to which the user currently belongs. 

    About the segid parameter…

    Use the  segid  parameter to send the complete list of audience segment IDs to which the user belongs. This means that any subsequent request for that user with the segid parameter overwrites the user’s already existing segments list. It is incorrect to send segid along with addseg or remseg in the same request.
  • [last_known_user_IP_address]  - replace with the last known IP address of the user. If unknown, then exclude this parameter from the request. This parameter is optional when you send Country Code a request.
  • [country_code] - replace with the two-character code of the user's country; for example, US, IN, CA. If unknown, then exclude this parameter from the request. This parameter is optional when you send the IP address in the request.
  • [comma_separated_list_of_segment_IDs_to_be_appended]  - replace with a comma-separated list of new audience segment IDs to be appended to the user’s current list of segment IDs.

    You can send either…

    • The segid parameter with a complete list of segments to replace the user's current segments. 
    • The addseg parameter with the list of new segments to append to the user’s current segments.

    DO NOT send both segid and addseg in the same request.

  • [comma_separated_list_of_segment_IDs_to_be_removed] - replace with a comma-separated list of any audience segments IDs that must be removed from the user’s current list of segment IDs.

    You can send either…

    • The segid parameter with a complete list of segments to replace the user's current segments. 
    • The remseg  parameter with the list of segments to remove from the user’s current segments.

    DO NOT  send both segid and remseg in the same request.

Sample server-to-server integration requests

  1. In this request, 89 indicates the identifier assigned by PubMatic to the data partner, B8CB98E6-0FF0-4C2B-A161-4F89155C28F indicates the PubMatic user ID and the user belongs to three segments with IDs - 123, 98901 and 4532. The last known IP of the user was 74.125.236 and the user is from the US. Please note that these segments 123, 98901 and 4532 are IDs of audience segments in the DMP system.
  2. http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=B8CB98E6-0FF0-4C2B-A161-4F89155C28F&ip=74.125.236&country=US&addseg=3242&remseg=123
    In this request for the same user, segment ID 3242 needs to be appended to the user’s existing list, and segment ID 123 needs to be removed from it, that is, the final user’s list of segments is 98901, 4532 and 3242.


Note: It is mandatory to send either the IP address or the Country Code in the API request to PubMatic.

Note: The data partner should periodically transfer data (typically once in every 3 hours) using this API URL to PubMatic.

Note:  Segment IDs being passed are the segment IDs in the DMP system. Do not pass PubMatic IDs in the ingestion requests

Browser-side real-time (HTTP 302 redirect) data transfer

Data partners who do not support the server-to-server data transfer mechanism can pass the data to PubMatic using the browser-side real-time data transfer mechanism for each visitor. This implementation is depicted in the following figure.

  1. A user visits the website using a browser, which upon loading, executes the PubMatic pixel.
  2. The PubMatic pixel invokes the data partner's pixel or URL to request the audience segment data for this visitor. To reduce the latency, this request is sent to the data partner only once in a pre-configured time interval (e.g., once per day) per user.

The data partner's system then redirects to the PubMatic Data Ingestion API using the HTTP 302 redirect. This API URL will be shared by PubMatic with the data partner before the start of the integration. While redirecting to the API URL, the data partner's system should include all the IDs of the audience segments to which the visitor belongs.

Note: The data partner also needs to provide the segment ID-to-segment name mapping to PubMatic only once at the start of the integration.

Data Ingestion API format (browser-side)

The PubMatic Data Ingestion API URL for the browser-side real-time data transfer:


http://aud.pubmatic.com/AdServer/Artemis?dpid=[data_partner_ID_assigned_by_PubMatic_at_the_
time_of_integration]&segid=[comma_separated_list_of_segment_IDs]&addseg=[comma_separated_

list_of_segment_IDs_to_be_appended]&remseg=[comma_separated_list_of_segment_IDs_to_be_

removed]

In the above API URL, the data partner needs to replace the following variables with actual values during each request:

  • [comma_separated_list_of_segment_IDs]  should be replaced with a comma-separated list of IDs of all the audience segments to which the user currently belongs.
  • [comma_separated_list_of_segment_IDs_to_be_appended]  should be replaced with a comma-separated list of IDs of the audience segments which need to be appended to the user’s existing list of segment IDs.

    Note: You can either send the complete list of segments for a user using the segid parameter or just send the list of segments to be appended to the user’s segments’ list using this addseg parameter. It is incorrect to send both segid and addseg in the same request.
  • [comma_separated_list_of_segment_IDs_to_be_removed] should be replaced with a comma-separated list of IDs of the audience segments which need to be removed from the user’s existing list of segment IDs.

    Note: You can either send the complete list of segments for a user using the segid parameter or just send the list of segments to be removed from the user’s segments’ list using this remseg parameter. It is incorrect to send both segid and remseg in the same request.

The value of  [data_partner_ID_assigned_by_PubMatic_at_the_time_of_integration] will be shared by PubMatic with the data partner at time of integration.

Sample browser-side real-time data transfer requests:

  1. http://aud.pubmatic.com/AdServer/Artemis?dpid=89&segid=123,98901,4532
    In this request, 89 indicates the identifier assigned by PubMatic to the data partner and the user belongs to three segments with IDs - 123, 98901 and 4532.
  2. http://aud.pubmatic.com/AdServer/Artemis?dpid=89&addseg=3242&remseg=123 
    In this request for the same user, segment ID 3242 needs to be appended to the user’s existing list, and segment ID 123 needs to be removed from it, that is, the final user’s list of segments is 98901, 4532 and 3242.

Bulk audience data transfer using SFTP

Use the following information to transfer audience segment data to PubMatic over SFTP.

File Format

Before submitting your segment data, ensure every row in the file is formatted as follows:

[DataProvider_ID] [TAB] [PubMatic_User_ID] [TAB] [Segment_IDs] [TAB] [Last_Known_User_IP_Address] [TAB] [Country_Code] 

ATTRIBUTE

DESCRIPTION

DataProvider_ID 

The PubMatic ID assigned to this data provider at the time of integration.

PubMatic_User_ID PubMatic's unique identifier for a user. PubMatic uses this ID for cookie sync.
Segment_IDs 

A comma-separated list of segments that include the user. To remove a user from all previous audiences, do not pass any segment ID. PubMatic stores the audiences in the latest record, overwriting the user's previous audiences. Be sure to have all the user's audiences in a comma-separated format and not only the delta.

Segment IDs should be those already registered by the DMP with PubMatic…

These IDs are from the DMP’s platform and not the ones assigned by PubMatic on registration. Comma-separate multiple segment IDs and include only one user ID per line.
Last_Known_User_IP_Address The last-known IP address of the user. If unknown, exclude this parameter from the request. This field is optional when providing [Country_Code.
Country_Code 

The two-character code of the user's country; for example, US, IN, CA. If it unknown, exclude this parameter from the request. This field is optional when providing,[Last_Known_User_IP_Address].

You must provide either…

[Last_Known_User_IP_Address] or [Country_Code]. If[Last_Known_User_IP_Address] is unknown, add two TABs between segment ID and country code with no additional blank/space characters.

File name convention

File names follow the pattern,  <DMPID>_<TIMESTAMP>_<MD5SUM>.tsv . While the transfer is in progress, suffix the file with.UPLOADING , then rename it on completion. We support compression formats such as gzip bzip2 , and others. If you are compressing the data file, add the additional compression type suffix; for example, .tsv.gz .

Segment Registration

Before sending data for specific segment IDs in the TSV file, you should have already registered the segments with PubMatic. You can either email PubMatic any new segment names and segment IDs you want to register or use the PubMatic Audience Registration API for to do so.

Sample entries

103   5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D    4666        US 

103   34E1EA68-8EDA-4254-9BD0-AB24BCC13914    4666        US 


Bulk transfer notes…

  • FTP allows a single user to do a batch upload, while HTTP allows only one user to be sent in a single call.
  • HTTP lets a DMP add or remove a segment for a given user id, but FTP requires the DMP to send all the user's segment IDs, which overrides the existing segment stored with PubMatic.
  • FTP allows only one new line entry for each segment for a given user.

Host and access

            Provided separately by PubMatic. Contact your PubMatic account manager with questions.

Remove a user from audiences 

Use one of the following methods to remove a user from all of their audiences (DMPs and publishers can use either method). 

  • When sharing data via Server-to-Server (S2S) call or browser redirect mechanism, exclude the segid parameter from the S2S call to PubMatic.
    EXAMPLES:
    http://aud.pubmatic.com/AdServer/Artemis?dpid=[data_partner_ID_assigned_by_PubMatic_at_the_ time_of_integration]&userid=[PubMatic_User_ID] 

    OR

    To send a list of segments to remove using the remseg parameter:
    http://aud.pubmatic.com/AdServer/Artemis?dpid=[data_partner_ID_assigned_by_PubMatic_at_the_ time_of_integration]&userid=PubMatic_User_ID]&remseg=[comma_separated_list_of_segment_IDs_to_be_removed]


  • When sharing data via a bulk file, do not pass any segment ID in the file for the user record. Audiences in the latest record are stored for the user ID, overwriting the user's previous audiences. 


⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents