# 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](https://support.google.com/faqs/answer/2727482).

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"
         }
       ]}