Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Apply image and text update for TW-1001

...

Data integration requires these steps:

  1. Audience Source creation
  2. Audience registration
  3. Data transfer

Audience Source creation

Registering audiences requires an Audience Source/data partner ID (DPID); see, Create and Edit an Audience Source.

...

You can bulk-register audiences by uploading a correctly formatted CSV file. Download To download the CSV template from PubMatic:

  1. Click the Bulk Upload Audiences drop-down (circled in red above), then choose the Bulk Upload Audiences menu item.
  2. In the Upload Audiences dialog click, Download Create Template, which is the one you use to create your audiences. When it's time to update your audiences, then you would use the Download Update Audiences template.
  3. After you've filled in the template with your audience data (note the required fields), then return to the Upload Audiences dialog and click Select File.
  4. When the Upload Audiences dialog displays the name of your template file, click Upload Audiences to send it to PubMatic and close the dialog.

Data transfer

Transfer audience data to PubMatic using one of the following methods:

Note
titleImportant

PubMatic automatically removes user IDs older than 30 days. The best practice is to refresh data at least every 25 days.

...

Parameter

Type

Required

API

SFTP

Description

dpid

integer

yes

yes

PubMatic data partner ID (DPID) assigned to the data partner at time of integration.

userid

string

yes

yes

The PubMatic user ID passed to the data partner by PubMatic.

uidtype

integer

yes

yes

A integer value that determines what the identity partner's PubMatic user ID represents:

  •     0 = UID represents a PubMatic cookie ID. Note: when using uidtype=0, you must first perform the UID sync step below.
  •     1 = UID represents a device ID.
  •     A different identity partner ID registered with PubMatic.
Note
titleuidtype is now required for all new integrations

Contact your PubMatic account manager to learn more about UID Type assignment and other identity partners supported by PubMatic.


segid

string array


yes

yes

Use segid to send the complete list of audience IDs to which the user belongs. Each subsequent request for that user with the segid parameter overwrites the user’s already existing audiences list.

DO NOT send segid in a request that also includes the addseg or remseg parameters.

Omitting segid removes the entire list of the user's audiences; see, Remove a user from audiences.

addseg

string array


yes

no

Use addseg to send:

  • A complete list of comma-separated audience IDs to replace the user's current audiences.
  • A list of new audiences to append to the user’s current audiences.

You can include addseg and remseg in the same request, but DO NOT send segid along with these parameters.

remseg

string


yes

no

Use remseg to send:

  • A complete list of comma-separated audience IDs to replace the user's current audiences. 
  • A list of audiences to remove from the user’s current audiences.

You can include remseg and addseg in the same request, but DO NOT send segid along with these parameters.

ip

string


yes

yes

Last known IP address of the user; optional when you send country in the request. Omit this parameter from the request if the user's last IP address is unknown.

country

string


yes

yes

Two-letter code for the user's country; for example,  US, IN, CA; optional when you send the last known ip in the request. Exclude this parameter from the request if the user's country is unknown. If both country and ip are omitted, country defaults to US.

...

Server-to-server data transfer is the best practice for submitting data to PubMatic since the servers communicate directly, so data transfer is highly-efficient. Build API calls using the parameters from the data transfer parameter table and make HTTP calls to the API endpoint:

...

  • 89 is the data partner's PubMatic-assigned ID (DPID).
  • The user belongs to three audiences with IDs 123_B, 98901, and 4532.
  • uidtype=0 means the user ID represents a cookie ID.

    Info

    If your user IDs represent PubMatic cookie IDs, you must first use UID sync .


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

...

  • 89 is the data partner's PubMatic-assigned ID.

  • B8CB98E6-0FF0-4C2B-A161-4F89155C28F is the PubMatic user ID (from UID sync).

  • the last known IP of the user: 74.125.236.123.

  • the user's country: US.

  • the user's DMP source audience IDs: 123_B, 98901, and 4532.

  • uidtype=0 specifies that the user ID should be handled as a cookie ID (use UID sync when passing uidtype=0).

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_B,98901,4532&uidtype=0

...

For more information on all available parameters, see Data transfer parameters.

Bulk audience data transfer using SFTP

...

The [SEGID] parameter refers to the Source Seg ID that was assigned to the audience during audience registration. You can submit multiple, comma-separated, source audience ID's.

For more information on the other parameters, see Data transfer parameters.

Note
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. If neither [IP] nor [COUNTRY] are added to the entry, PubMatic will set the [COUNTRY] to US by default.

...

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

  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.

    EXAMPLES:

    Code Block
    http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D&uidtype=[Identity_Partner_ID]

    OR

    To send a list of audiences to remove using the remseg parameter: 

    Code Block
    http://aud.pubmatic.com/AdServer/Artemis?dpid=89&userid=5AFCD4CD-F9B6-4E53-B63D-BFB2CF44941D&remseg=123_B,3242&uidtype=[Identity_Partner_ID]


  2. When sharing data via a bulk file, do not pass any audience 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.

...