OpenRTB 2.1PubMatic User Sync-Up Pixeling

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Jun 6, 2017
Version 2Show Document
  • View in full screen mode

PubMatic supports an optional mechanism to sync-up users seen by PubMatic with Demand Partners through pixels.

Parameters

                                 

Parameter

Mandatory

Multi-Valued

Description

vcode

Yes

Yes

Code for the Pixel will be provided by PubMatic to the Demand Partner. This value would be different for adding/removing a Pixel

piggybackCookie

No

No

Demand Partner shall pass the value to set the cookie outside of the RTB API call. Any user cookie that Demand Partner wishes to set via PubMatic; this information will be passed to the Demand Partner if present in the call via the “cookie” parameter in the bidding call. Restricted to 256 bytes.

r

No

No

Demand Partner can specify a URL (can be encoded) for redirection. After setting the pixel, there would be a 302 redirection to that specified URL.

puid

No

No

If the Demand Partner wants to fetch the PubMatic user ID of the given user, then it should include “puid=${PUBMATIC_UID}” in the response. In such cases, PubMatic will replace the “${PUBMATIC_UID}” macro with its user ID and send it back in the response. If the PubMatic user ID does not exist for that particular user, then this macro will be empty.

 

How it works:

  1. PubMatic sees the user for the first time in a specific time interval (default is 15 days).
  2. PubMatic invokes the Demand Partner pixel which also contains a redirection URL (encoded) to the PubMatic pixel.
  3. Demand Partner pixels the user and thus assigns a user ID or other parameter. The user ID or other parameter is appended to the PubMatic pixel URL.
  4. Demand Partner then redirects to the PubMatic pixel URL by passing user ID or other parameter (in the context of the Demand Partner) as the “custom data” parameter. Content of the custom data parameter is completely controlled by the Demand Partner and it is stored and passed as is by PubMatic.
  5. PubMatic pixels the user, storing the custom data value (user ID or other parameter) sent by the Demand Partner and redirects to the specified URL if any.
  6. Demand Partner sees the custom data value stored for user ID or the other parameter it has set in the RTB API bid requests.

A sample scenario where user ID is synced up between PubMatic and Demand Partner-

  1. PubMatic calls the Demand Partner when PubMatic sees the unique user.
    Added and appended with PubMatic piggyback pixel (JS).
    Example:
    http://syncup.demandpartner.com/getuid?http://image2.pubmatic.com/AdServer/Pug?vcode=abcdR5cGU9MSZqcz0xJmNvZGU9NzgmdGwddddwMCZxyze13&piggybackCookie=uid:$UID
  2. Demand Partner sets a cookie uid=<value>
  3. Demand Partner redirects to the PubMatic pixel with user ID value filled in.
    http://image2.pubmatic.com/AdServer/Pug?vcode=abcdR5cGddddqcz0xJmNvZGU9ODImdGw9MTU3NjgwMCZxyze13&piggybackCookie=uid:7871669318&r=http://syncup.adnetwork.com/rp;puid=${PUBMATIC_UID}
Note: For more information about the parameters included in this response, refer to the Parameters table.
  1. PubMatic stores the value in the piggyback cookie which redirects to the URL provided.
  2. PubMatic passes the piggyback cookie value in the API request parameter.

As a part of the pixel policy, PubMatic requires DSPs to drop pixels on the publishers served through PubMatic based on the following policy.

This will help to minimize the latency on the publisher’s page and also provide a better user experience to all users.

  • Policy:
    • Before a creative is served (PubMatic-initiated pixel sync only) – not more than a total of 3 pixels:
      • Redirects to 2nd party partners (advertisers) are allowed.
      • Redirects to 3rd party partners (data providers, exchanges or SSPs) are not allowed.
    • After a creative is served, not more than a total of 5 pixels:
      • Redirects to 2nd party partners (advertisers) are allowed.
      • Redirects to 3rd party partners (only data providers) are allowed.
      • Redirects to 3rd party partners (exchanges, SSPs or competitors) are not allowed.
  • Penalty for not adhering to the above policy:
    • PubMatic will block the DSP's pixel on the PubMatic-initiated sync once a violation has been communicated to the DSP, and if no corrective action is taken.

Attachments

    Outcomes