Use this guide to integrate your audience segments with the PubMatic system.
Integration requirements
Get PubMatic's API Token: provide PubMatic with the developer's First Name, Last Name, and Email Address to create an API authentication token.
Info title To learn more… See, Getting Started with PubMatic APIs. Integration also requires a data partner ID (DPID).
Info title To learn more…
Data integration
Info | ||
---|---|---|
| ||
|
Data integration requires these steps:
Segment registration
Info | ||
---|---|---|
| ||
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:
- Register segments with the Segment Registration APIs; see, Register an Audience segment, to learn more.)
- Bulk-register segments in the PubMatic system UI using the menus, Publisher Account > Audience > Audience Segments > Bulk Upload Segments:
Data transfer parameters
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:
- Server-to-server (S2S) data transfer
- Browser-side real-time (HTTP 302 redirect) data transfer
- Remove a user from audiences
- Bulk audience data transfer using SFTP
Comment |
---|
dsimerly - You can find the following common table is within the document, Audience > SFTP Data Transfer for Audience Segments. |
Excerpt Include | ||||||
---|---|---|---|---|---|---|
|
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:
- A user lands on a web page.
- PubMatic and a data provider receive the UID.
- PubMatic syncs with the data provider by sharing the data transfer API URL.
- 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.
Info | ||
---|---|---|
| ||
Data partners must transfer the updated audience profile information to PubMatic in batches. |
Server-to-server sample requests
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 | ||||
---|---|---|---|---|
| ||||
http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=B8CB98E6-0FF0-4C2B-A161-4F89155C28F&segid=123,98901,4532&country=US&uidtype=0 |
This request for the same user appends segment ID 3242
to the user's existing list and removes segment ID 123
from the list, changing the user's audience segments list to: 98901,
4532
,3242
. The uidtype
parameter also specifies using the UID
value as a device ID.
Code Block | ||||
---|---|---|---|---|
| ||||
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
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 as follows:
- A user visits the website using a browser, which upon loading, executes the PubMatic pixel.
- 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 per user; for example, once per day.
- 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.
Info | ||
---|---|---|
| ||
Provide the segment ID-to-segment name mapping to PubMatic only once at the start of the integration. |
Browser-side sample requests
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 | ||||||
---|---|---|---|---|---|---|
| ||||||
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 |
This request for the same user show that, B8CB98E6-0FF0-4C2B-A161-4F89155C28F
is the PubMatic user ID, the last known IP of the user was, 74.125.236.123
, and the user is from the US
. Next, addseg
instructs that audience segment 3242
will be appended to the user's existing list of audience segments, while remseg
instructs that audience segment 123 will be removed, leaving the user's updated audience segments as: 98901,4532,3242
. Finally, uidtype=1
specifies that the user ID should be handled as a device ID.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
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 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]
- 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.
Comment |
---|
dsimerly - 1/10/2021 - The following excerpt is shared with the document, Audience > SFTP Data Transfer for Audience Segments. |
Bulk audience data transfer using SFTP
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:
The segid parameter can be a comma-separated list of different audience segment IDs. See Data transfer parameter reference above.
File name formatFile names follow the pattern: <DPID>_<TIMESTAMP>_<MD5SUM>.tsv.gz
If your organization has workload managed by a team, you can also include a <DPID>_<TIMESTAMP>_<MD5SUM>_<WORKERID>.tsv.gz
PubMatic supports compression formats such as,
Segment registrationBefore 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
Host and accessProvided separately by PubMatic. Contact your PubMatic account manager with questions. Unique identifier (UID) sync
Steps for user sync-up:
|