Direct Proof of Play API (DPoP-API)

ALPHA API - Requires Android Player 24+

The Direct Proof of Play API (DPoP-API) is a callback mechanism for notifying 3rd party servers when an item is displayed. When configured, players will make a HTTP POST directly to your own server when an item is displayed.

This API enables real-time data to be collected and processed by your server. Data can include a screenshot to enhance reports that are delivered to advertisers.

Please note that a reliable network connection is required for DPoP to operate. We recommend using our built-in reporting functionality when possible as this collects playback data when offline and protects against data loss in an unreliable network environment.

DPoP Configuration

Example DPoP-API configuration added to item, sequence or screen data:

dpopEndpoint=http://example.com/dpop-receiver
dpopTrigger=display+3s
dpopCondition=itemId=="ABCDEF123"&&time.between("9:00","17:00")
dpopType=SCREENSHOT

This will instruct the player to take a screenshot 3 seconds after the item with the item ID ABCDEF123 is displayed between 9am and 5pm and post it to http://example.com/dpop-receiver.

This dpopEndpoint is the web address of the server page that will receive the DPoP data. Data will be HTTP POSTed to this server when configured to do so by dpopTrigger and dpopCondition.

The dpopTrigger is the player operation that will start the DPoP communications. This is typically set to display. This will trigger a DPoP POST when a new item starts displaying. This can be configured further by adding a delay value in seconds. For example display+3s will delay the action by 3 seconds which is useful if a screenshot needs to be captured. The dpopTrigger can also be set to download. This will make a DPoP POST when an item finishes downloading and is ready for displaying in regular sequence playback.

The dpopCondition enables the DPoP POSTs to be limited to prevent overwhelming the target server. It might be desirable to only receive proof of play data for specific items or between specific time periods. The full range of TargetR conditional logic can be applied to the current playback state. For example, you could add a variable importantItem=1 to an item's data and set dpopCondition=importantItem==1 to ensure you only receive DPoP POSTs for that item (and other items with importantItem=1 set).

The dpopType supports 4 different types of data posting:

  1. DATA - Posts full item data and screen data to the dpopEndpoint.
  2. SCREENSHOT - Post a screenshot to the dpopEndpoint.
  3. SHORT - Post only itemId, libraryItemId, customId and screenId to the dpopEndpoint.

DPoP Data

All DPoP POST will include the following HTTP headers.

X-DPoP-Type: [dpopType]
X-DPoP-Trigger: [dpopTrigger]
X-ItemId: [itemId]
X-ItemLabel: [itemLabel]
X-LibraryItemId: [libraryItemId]
X-CustomId: [customId]
X-ScreenId: [screenId]

Depending on the dpopType, the body of the HTTP Post will differ.

For DATA, the body is a JSON response containing the full item data and the full screen data.

{
  item : {
    id : "ABCDEF123",
    data : {
      label : "My item label",
      libraryItemId : "ABCDEF123",
      ...
    }
  }
  screen : {
    id : "1234567890AB",
    data : {
      "label", "My screen label",
      ...
    }
  }
}

For SHORT, the body only contains itemId, customId, libraryItemId and screenId:

{
  itemId : "ABCDEF123",
  customId : "my-custom-internal-item-id",
  libraryItemId : "ABCDEF123",
  screenId : "1234567890AB"
}

For SCREENSHOT, the body is binary JPEG image data (image/jpeg).

 

Multiple DPoP

Sometimes it is necessary to make multiple calls when displaying an item. For example, to send data to multiple endpoints or at different playback positions or provide different types of callback. This is made possible by numbering the DPoP configurations.

The first DPoP configuration should be affixed with _0 as follows:

dpopEndpoint_0=http://example.com/dpop-receiver
dpopTrigger_0=display
dpopType_0=DATA

Then incremented sequentially:

dpopEndpoint_1=http://example.com/dpop-screenshot-receiver
dpopTrigger_1=display+3s
dpopCondition_1=itemId=="ABCDEF123"&&time.between("9:00","17:00")
dpopType_1=SCREENSHOT

 

DPoP Defaults

Each DPoP configuration must include dpopEndpoint. When undefined, the following dpopTrigger, dpopCondition and dpopType are applied:

dpopTrigger=display
dpopCondition=true
dpopType=DATA