DDM Integration for Third-Party App Tracking

The following end-to-end flow describes both advertiser setup and third-party implementation required in order to run a campaign on DoubleClick buy-side products using a third-party app tracking solution.

For more information about DoubleClick Digital Marketing in general as well as an overview of in-app attribution features, see the DoubleClick Digital Marketing background page.

  1. Advertiser sets up Conversion event in DDM to represent the install or conversion (Bid Manager only - conversion pixel) (Campaign Manager - Floodlight activity).

  2. Advertiser "links" DDM conversion event in the third-party interface and provides key variables that identify an advertiser and conversion activity group.

    • src is the advertiser ID that is the source of the Floodlight activity.
    • cat is the activity tag string, which Floodlight servers use to identify the activity group to which the activity belongs.
    • type is the group tag string, which identifies the activity group with which the Floodlight activity is associated.
    • u1, u2, ... (if available) are the custom Floodlight variable key-values.

  3. Advertiser adds variables to signify consent collection for DMA compliance.

    • eea is used to identify EEA users.
      • eea=0 indicates that the user is not from the EEA.
      • eea=1 indicates that the user is from the EEA.
    • ad_user_data is the consent flag for the use of user data for ads purposes.
      • Only needs to be set if eea=1
      • ad_user_data=0 indicates the user has denied consent for transmission of user level data to Google for ads purposes.
      • ad_user_data=1 indicates the user has granted consent for transmission of user level data to Google for ads purposes.
    • npa is used for ad personalization content.
      • npa=0 indicates the user consents to personalization.
      • npa=1 indicates the user has not consented to personalization.
    • test_request_reason=dma can be used to test DMA parameters
      • Validates all DMA parameters and returns warnings.
      • Returns multi-response with fake clicks.
      • Logs the conversions as test conversions.

  4. In addition, the advertiser needs to provide third parties with its specific authorization token:

    token is an advertiser-specific alphanumeric string that must be passed along with each server request to DDM.

  5. Advertiser runs in-app ad campaign with ad tags served by DBM on real-time bidding exchanges or served by DCM on direct-bought media.

  6. End user sees and clicks on ads, which are logged by DDM.

  7. When end user installs the app or completes a conversion event, such as "game play", third-party servers "ping" DDM on every app activity:

    An example URL for user not in EEA

    https://ad.doubleclick.net/ddm/s2s/appactivity/src=1234567;cat=fghij456;type=abcde123;u1=[friendlyname1];ord=1312312312;eea=0;npa=0

    An example URL for user in EEA

    https://ad.doubleclick.net/ddm/s2s/appactivity/src=1234567;cat=fghij456;type=abcde123;u1=[friendlyname1];ord=1312312312;eea=1;ad_user_data=1;npa=0

    where:

    • src is the advertiser ID that is the source of the Floodlight activity.
    • cat is the activity tag string, which Floodlight servers use to identify the activity group to which the activity belongs.
    • type is the group tag string, which identifies the activity group with which the Floodlight activity is associated.
    • ord is a random number that is used to make the Floodlight tag unique.
    • u1, u2, ... (if available) are the custom Floodlight variable key-values.
    • eea identifies if the user is in the EEA.
    • ad_user_data identifies if the user consents to cookies and Measurement.
    • npa identifies if the user consents to personalization.

    with additional parameters sent through a JSON payload in an HTTP POST:

    {
  "app": {
    "bundle": "com.rovio.angrybirds"
  },
  "device": {
    "ua": "Mozilla/5.0 (KHTML, like Gecko) Version/6.0 Mobile/10A5376e Safari/8536.25",
    "ip": "108.176.57.230",
    "didmd5": "A2D2DA47AC2DE1BCA16883BD5CAA6F2F",
    "lmt": 1
  }
}

    and the advertiser authorization token is passed in the HTTP Authorization Header:

    Authorization: Token token="[advertiser authorization token string]"

    where:

    • app (required) is the JSON object representing the app where the conversion activity took place. Use app: {} if the app where the conversion activity took place is not available.
    • bundle (if available) is the app object field containing a string value of the Play Store bundle name or App Store ID.
    • device is the JSON object representing the device on which the conversion activity took place.
    • ua is the device object field representing the user agent string of the app where an activity was recorded. This parameter is required.
    • ip (if available) is the device IPv4 address assigned to the device. This parameter is required.
    • didmd5 is the MD5-hash string of the uppercased IDFA or Google Play Advertising ID value.
    • lmt is an integer, with a value of 1 if the user has enabled the "Limit Ad Tracking" option with IDFA or AdID, or 0, if not set.

    DDM will respond with a JSON response of whether the conversion event is attributed to a view or click served by DCM, and if "YES", additional information about the event (last view or click):

    • Ad ID
    • Site ID
    • Placement ID
    • Creative ID
    • Timestamp

    An example JSON response might look like:

    {
  "attributed": 1,  // Whether the conversion can be attributed to a DCM event.
  "last_impression_ad_id":283641088,
  "last_impression_site_id":1408067,
  "last_impression_placement_id":107616368,
  "last_impression_creative_id":60162352,
  "last_impression_timestamp":1415647607,
  "last_click_ad_id":283641088,
  "last_click_site_id":1408067,
  "last_click_placement_id":107616368,
  "last_click_creative_id":60162352,
  "last_click_timestamp":1415647657,
  "last_click_exclid":"CKm0nLKhyssCFceH2wod8l4I4A",
  "cps": <cps>,
  "ad_events": [
    <ad event objects>
  ],
  "warnings": [<warning strings>],
  "errors": [<error strings>],
}

    where:

    • attributed is value 1 (if the conversion can be attributed to an impression or click) or 0 (if not attributable).
    • last_impression_ad_id (if attributed = 1) is the ad ID for the last impression.
    • last_impression_site_id (if attributed = 1) is the site ID for the last impression.
    • last_impression_placement_id (if attributed = 1) is the placement ID for the last impression.
    • last_impression_creative_id (if attributed = 1) is the creative ID for the last impression.
    • last_click_ad_id (if attributed = 1 and a click was attributed) is the ad ID for the last click.
    • last_click_site_id (if attributed = 1 and a click was attributed) is the site ID for the last click.
    • last_click_placement_id (if attributed = 1 and a click was attributed) is the placement ID for the last click.
    • last_click_creative_id (if attributed = 1 and a click was attributed) is the creative ID for the last click.
    • last_click_exclid corresponds to a unique click ID populated using the %eiid! macro

    Beginning with DMA enforcement in March 2024, the following fields will also be available:

    • cps indicates which Core Platform Service the event belongs to
      • a : Ads
      • m : Maps
      • p : Play Store
      • s : Search
      • h : Shopping
      • y : YouTube
    • ad_events is an array of ad_event objects containing all of the conversion events.
      • The ad_event object has the following fields:
      • product_type is a string that reports the product responsible for the conversion. This will be either DCM or DBM.
      • interaction_type is the type of interaction that lead to the event. Either impression or click.
      • conversion_metric is the conversion metric used for attribution. Either conversion or view_through_conversion.
      • timestamp is the UNIX timestamp the ad event occurred with microsecond precision. This value should be used for last-click attribution.
      • campaign_type identifies the type of campaign that produced the ad event.
      • line_item_id (DBM only) is the DBM line item ID that produced the ad event.
      • line_item_name (DBM only) is the name of the DBM line item that produced the ad event.
      • placement_id (DCM only) is the DCM placement tag ID that produced the ad event.
      • placement_name (DCM only) is the name of the DCM placement tag that produced the ad event.
      • external_customer_id is the advertiser identifier that owns the campaign that produced the ad event.
        • If product is DBM this field represents the DBM Advertiser ID.
        • If product is DCM this field represents the DCM Advertiser ID.
      • creative_id is the ID of the creative ad unit that produced the ad event.
        • If product is DBM this field represents the DBM Creative ID.
        • If product is DCM this field represents the DCM Creative ID.
      • exchange_id (DBM only) is the ID of the exchange that served the DBM ad.
      • insertion_order_id (DBM only) is the DBM insertion order ID.
      • site_id (DCM only) is the DCM site ID for the ad event.
      • cps indicates which Core Platform Service the ad event belongs to. Refer to the full explanation of the cps field earlier in the documentation for further details.
    • warnings is an array of warnings produced by the conversion event.

    • errors is an array of errors produced by the conversion event with HTTP error codes, for the following scenarios:

      • HTTP 204 if the request quota has been exceeded.
      • HTTP 400 when the request is considered invalid—for example, missing required parameters, and the server has fallen back to pixel tracking.
      • HTTP 401 if the authorization token is invalid.
      • HTTP 404 for any bad requests.

    Advertiser will be able to see campaign reports in your system; advertiser will also be able to see conversion reports in DCM with the same parameters.

    Additional example responses after DMA is enforced in March 2024

    An example of an attributed conversion tracking response where the conversion is attributed to both Search + YouTube ad interactions but 5(2)(b) + 5(2)(c) cross-use consent is denied between the Search + YouTube CPSs:

    {
  attributed: 1,
  last_impression_ad_id: 283641088,
  last_impression_site_id: 1408067,
  last_impression_placement_id: 107616368,
  last_impression_creative_id: 60162352,
  last_impression_timestamp: 1415647607,
  last_click_ad_id: 283641088,
  last_click_site_id: 1408067,
  last_click_placement_id: 107616368,
  last_click_creative_id: 60162352,
  last_click_timestamp: 1415647655,
  last_click_exclid: "CKm0nLKhyssCFceH2wod8l4I4A",
  cps: "s",
  ad_events: [{
      cps : "s",
      product_type: "DCM",
      interaction_type: "click",
      ad_event_type: "click",
      campaign_type: "Display",
      placement_id: 107616368,
      placement_name: "TEST PLACEMENT NAME",
      external_customer_id: 7480542,
      creative_id: 60162352,
      timestamp: 1415647655.123456,
      site_id: 1408067,
      }, {
      cps : "s",
      product_type:"DCM",
      interaction_type: "impression",
      ad_event_type: "impression",
      campaign_type: "Display",
      placement_id: 107616368,
      placement_name: "TEST PLACEMENT NAME",
      external_customer_id: 7480542,
      creative_id: 60162352,
      timestamp: 1415647607.123456,
      site_id: 1408067
      },{
      cps : "y",
      product_type: "DCM",
      ad_event_type: "click",
      campaign_type: "Display",
      placement_id: 107616370,
      placement_name: "Placement on Youtube",
      external_customer_id: 7480542,
      creative_id: 6016444,
      timestamp: 14344344.123456,
      site_id: 140806
      },
  ]}

    Example of an affirmative conversion tracking response for a DBM Campaign:

    {
  attributed: 1,
  last_click_ad_id: 283641088,
  last_click_site_id: 1408067,
  last_click_placement_id: 107616368,
  last_click_creative_id :60162352,
  last_click_timestamp: 1415647655,
  last_click_exclid: "CKm0nLKhyssCFceH2wod8l4I4A"
  cps: "y",
  ad_events: [{
    product_type: "DBM",
    interaction_type: "click",
    ad_event_type: "click",
    campaign_type: "Display",
    line_item_id: 123456789,
    line_item_name: "TEST LINE ITEM NAME",
    external_customer_id: 2550,
    creative_id: 512333,
    exchange_id: 132,
    insertion_order_id: 523423,
    timestamp: 1432681913.123456
    cps: "y"
  },
  {
    product_type: "DCM",
    interaction_type: "click",
    campaign_type: "Display",
    placement_id: 9342323,
    placement_name: "TEST PLACEMENT NAME",
    external_customer_id: 7480542,
    creative_id: 8234234,
    timestamp: 1432681913.123456,
    cps: "y"
  }
]}