Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Minor error fixed on Bulk audience data transfer (USERID instead of PUBID)

...

Data integration requires these steps:

  1. Segment registration.

  2. Data transfer.

Segment registration

Info
titleRegister segments ONLY ONCE before data transfer…
Perform registration only for any new segments you send.

...

Use Data Transfer API calls to send data to PubMatic. Build API calls using the parameters in the table below to transfer data demonstrated by samples for the following methods:

Comment

dsimerly - You can find the following common table is within the document, Audience > SFTP Data Transfer for Audience Segments.

...

In this request, 89  is the data partner's PubMatic-assigned ID, the user belongs to three audience segments (with IDs 123 , 98901 , and 4532 ), and uidtype=0 means the user ID represents a PubMatic cookie ID, and that you must first use the UID sync step below when passing 0 in uidtype

Code Block
languagexml
titleStandard call with segment IDs
http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=B8CB98E6-0FF0-4C2B-A161-4F89155C28F&segid=123,98901,4532&country=US&uidtype=0

...

Code Block
languagexml
titleAppending and removing segments
http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=B8CB98E6-0FF0-4C2B-A161-4F89155C28F&addseg=3242&remseg=123&country=US&uidtype=1

See Data transfer parameter reference above.

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

...

In this request, 89 indicates the data partner's PubMatic-assigned ID, B8CB98E6-0FF0-4C2B-A161-4F89155C28F is the PubMatic user ID (from the UID sync step above ), and the user belongs to three DMP audience segments with IDs: 123, 98901, and 4532. The last known IP of the user was, 74.125.236.123, the user is from the US, and uidtype=0 specifies that the user ID should be handled as a cookie ID (you must first use  the UID sync step below when passing 0 in uidtype).

Code Block
languagejs
titleCall updates entire audience segments list
linenumberstrue
http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=B8CB98E6-0FF0-4C2B-A161-4F89155C28F&ip=74.125.236.123&country=US&segid=123,98901,4532&uidtype=0

...

Code Block
languagejs
titleCall removes and appends audience segments list
linenumberstrue
http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=B8CB98E6-0FF0-4C2B-A161-4F89155C28F&ip=74.125.236.123&country=US&addseg=3242&remseg=123&uidtype=1

See Data transfer parameter reference above.

Remove a user from audiences 

...

  1. When sharing data via a Server-to-Server (S2S) call or browser redirect mechanism, exclude the segid parameter from the S2S call to PubMatic. See Data transfer parameter reference above.
    EXAMPLES: 
    http://aud.pubmatic.com/AdServer/Artemis?dpid=89 &userid=5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D&uidtype=[Identity_Partner_ID]

    OR

    To send a list of segments to remove using the remseg parameter:
    http://aud.pubmatic.com/AdServer/Artemis?dpid= 89&userid=5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D&remseg=123,3242&uidtype=[Identity_Partner_ID]

  2. 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.

...

Excerpt

You can use SFTP to transfer audience segment data to PubMatic within a tab-delimited file, where each row of the file contains the audience segment parameters separated by a tab character, with each row ending with a carriage-return as follows:

[DPID] [TAB] [PUBIDUSERID] [TAB] [SEGID] [TAB] [IP] [TAB] [COUNTRY] [TAB] [UIDTYPE]  [CR]

The segid parameter can be a comma-separated list of different audience segment IDs. See Data transfer parameter reference above.

Info
titleYou must provide either…
[IP] (last known IP address) or [COUNTRY] (two-letter country code). If [IP] is unknown, add two TABs between [SEGID] and [COUNTRY] with no additional blank/space characters. See Segment Registration > Sample entries below.

File name format

File names follow the pattern:

<DPID>_<TIMESTAMP>_<MD5SUM>.tsv.gz
  • <TIMESTAMP> format should be Unix; for example, 1596695461984.
  • <MD5SUM> is an MD5 32-character hexadecimal checksum that is computed on the file content before compression.

If your organization has workload managed by a team, you can also include a  <WORKERID>  as part of the file name to help track and manage the team member's workload:

<DPID>_<TIMESTAMP>_<MD5SUM>_<WORKERID>.tsv.gz


Note
titleWhile the transfer is in progress…

Suffix the file with, * .UPLOADING, then rename it upon completion.

PubMatic supports compression formats such as,  gzip  bzip2 and others. If you have any questions or issues uploading a compressed file, please contact your PubMatic account manager for assistance.

Note
The tsv.gz suffix must follow the uploaded file name. Please verify that the file name is correct once upload completes.

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 IDs you want to register, or use the PubMatic Audience Registration API to do so.

Sample entries

103   5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D    4666  74.125.236.123   0 

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

Info
titleBulk transfer notes…
  1. FTP lets a single user batch upload data for multiple partners, while HTTP allows data for only a single partner.
  2. 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.
  3. 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.

Unique identifier (UID) sync

Info
titlePubMatic can process data only from PubMatic User IDs…
To use data from other sources when using uidtype=0, 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 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.

...