Privacy Compliant App Attribution

Summary

API consumers that leverage Google Ads’ App Conversion Tracking and Remarketing API to directly pass app conversions should follow the following Android & iOS guidance. This will ensure clicks from users that opt out of ad tracking or ads personalization are only attributed using privacy compliant workflows. Please refer to the Request & Response Specifications Overview for additional information regarding parameter definitions and expected values.

Android Apps

Scope

App Install & App Engagement via all Google Ads campaigns

Background

Currently, Android users that have opted out of ads personalization cannot be tracked using Android Advertising ID (per Google’s policy). Instead, Google utilizes the gclid, a click URL parameter that does not persist with the device. Additionally, Google may use the gbraid, an aggregate click url parameter, in other scenarios where user-level consent has not been granted.

Guidance

App Conversion Tracking and Remarketing API consumers must ensure that the gclid and gbraid are correctly stored and passed.

Supported Scenarios

Supported Scenario: Install (user has not previously installed the app)

When an app install is driven by a deeplink that redirects to the Google Play store, and the user first opens the app, parse the gclid value from the Play Install Referrer API install_referrer field and store it either on device or server-side keyed by a 1st party identifier. Each value should be stored for 180 days, or until another more recent value. The gclid value should then be passed via the market_referrer_gclid conversion request field.

Advertising ID is Available

When Android Advertising ID is available, the market_referrer_gclid is required to be sent with the corresponding first_open event and ALL downstream sessions & app events (i.e. session_start,add_to_cart, in_app_purchase, etc.).

Example: First Open

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=advertisingid
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u

Example: Session and App Events

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=advertisingid
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u

Advertising ID is NOT Available

When Android Advertising ID is NOT available, the market_referrer_gclid is required to be sent with the corresponding first_open event, and ALL downstream sessions & app events (i.e. session_start, add_to_cart, in_app_purchase, etc.), along with additional field/value, gclid_only_request=1. Note: The rdid value should be all zeros (since the user is unconsented).

Example: First Open

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=first_open
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid_only_request=1

Example: Session & App Events

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid_only_request=1

Supported Scenario: App Engagement (user has already installed the app)

When an app session is driven by a deeplink, parse the gclid and gbraid values from the referring url and store them either on device or server-side keyed by a 1st party identifier. Each value should be stored for 180 days, or until replaced by another more recent value. The deeplink gclid value should then be passed via the gclid conversion request field, and the deeplink gbraid value should then be passed via the gbraid conversions request field.

Advertising ID is Available

When Android Advertising ID is available, the gclid and gbraid are required to be sent with the corresponding session_start event and ALL downstream sessions & app events (i.e. session_start,add_to_cart, in_app_purchase, etc.).

Example: Deeplink Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=advertisingid
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: App Events

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=advertisingid
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: Subsequent/Organic Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=advertisingid
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Advertising ID is NOT Available

When Android Advertising ID is NOT available, the gclid is required to be sent with the corresponding session_start event and ALL downstream sessions and app events (i.e. session_start, add_to_cart, in_app_purchase, etc.). Note: The rdid value should be all zeros (since the user has opted out of ads personalization).

Example: Deeplink Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: App Events

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: Subsequent/Organic Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Supported Scenario: Install + Engagement

When an app install is driven by a deeplink to the Google Play store, followed by an app session driven by a deeplink to the app, parse both the gclid value from the Play Install Referrer API install_referrer field, and the gclid and gbraid values from the referring url and store them either on device or server-side keyed by a 1st party identifier. Each value should be stored for 180 days, or until replaced by another more value. The install referrer gclid value should then be passed via the market_referrer_gclid conversion request field, the deeplink gclid value should be passed via the gbraid conversion request field.

Advertising ID is Available

When Android Advertising ID is available, both the market_referrer_gclid AND gclid are required to be sent with the corresponding session_start event and app events (i.e. add_to_cart, in_app_purchase, etc.). For downstream session_start events, pass the market_referrer_gclid, but the (deeplink) gclid should NOT be passed.

Example: Deeplink Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=advertisingid
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: App Events

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=advertisingid
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: Subsequent/Organic Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=advertisingid
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       <&gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Advertising ID is NOT Available

When Android Advertising ID is NOT available, both the market_referrer_gclid AND gclid are required to be sent with the corresponding session_start event, and ALL downstream session and app events (i.e. session_start, add_to_cart, in_app_purchase, etc.). Note: The rdid value should be all zeros (since the user has opted out of ads personalization).

Example: Deeplink Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: App Events

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: Subsequent/Organic Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=advertisingid
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &market_referrer_gclid=BX3QojHp4mY5MrJtFM_d1u
       &gclid_only_request=1
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Important: The Play Install Referrer API gclid (passed as market_referrer_gclid) and deeplink gclid (passed as gclid) are two separate sources for gclid values and should not be used interchangeably. As a reminder, these gclid values should be stored for 180 days, or until another more recent deeplink gclid replaces the existing deeplink gclid, or a Play Install Referrer API gclid replaces the existing Play Install Referrer API gclid. Conversely, the most recent gbraid value should always be passed as gbraid, regardless if sourced using the Play Install Referrer API or deeplink referring URL.

iOS Apps

Scope

App Engagement via Google Ads Search, Shopping, & iOS ACi + Deeplinks

Background

iOS14.5+ users who have not opted in to app tracking cannot be tracked using IDFA (per Apple’s ATT policy). Instead, Google utilizes the gbraid, an aggregate click url parameter. Additionally, Google may utilize the gbraid in other scenarios where user-level consent has not been granted.

Guidance

App Conversion Tracking and Remarketing API consumers must ensure that all click parameters are correctly passed, including the gclid and gbraid.

Supported Scenarios

Supported Scenario: App Engagement (user has already installed the app)

When an app session is driven by a deeplink, parse the gclid and gbraid values from the referring url, and store them either on device or server-side keyed by a 1st party identifier. These values should be stored for 180 days, or until replaced by a more recent value. The gclid value should then be passed via the gclid conversion request field, and the gbraid value should be passed via the gbraid conversion request field.

IDFA is Available

When IDFA is available, both the gclid AND the gbraid are required to be sent with the corresponding session_start event, along with additional field/value, app_open_source=ad_click. The gclid and gbraid are also required to be sent with downstream sessions & app events (i.e. session_start, add_to_cart, in_app_purchase, etc.). For subsequent downstream sessions, include additional field/value, app_open_source=organic.

Example: Deeplink Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
       &app_open_source=ad_click

Example: App Event

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: Subsequent/Organic Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=0F7AB11F-DA50-498E-B225-21AC1977A85D
       &id_type=idfa
       &eea=0
       &lat=0
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gclid=Cj0KEQjw0dy4BRCuuL_e5M
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
       &app_open_source=organic

IDFA is NOT Available

When IDFA is NOT available, the gbraid is required to be sent with the corresponding session_start event along with additional field/value, app_open_source=ad_click. and ALL downstream app events (i.e. add_to_cart, in_app_purchase, etc.). Note: The gclid field should be omitted, and the rdid value should be all zeros (since the user is unconsented). The gbraid is ALSO required to be sent with downstream sessions & corresponding app events (i.e. session_start, add_to_cart, in_app_purchase, etc.). For subsequent downstream sessions, include additional field/value, app_open_source=organic.

Example: Deeplink Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=idfa
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
       &app_open_source=ad_click

Example: App Event

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=in_app_purchase
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=idfa
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O

Example: Subsequent/Organic Session

POST /pagead/conversion/app/1.0
       ?dev_token=Z_eErE4DkvcKjDM1OVE4c4
       &link_id=31FF8D67E5BB5DD5029DCC2734C2F884
       &app_event_type=session_start
       &rdid=00000000-0000-0000-0000-000000000000
       &id_type=idfa
       &eea=0
       &lat=1
       &app_version=1.2.4
       &os_version=9.3.2
       &sdk_version=1.9.5r6
       &timestamp=1432681913.123456
       &gbraid=ChEI8IixhgYQrufHkIjz3YWRARIzALev_G_O
       &app_open_source=organic

Note: gbraid cannot be leveraged in Install scenarios since users are first redirected to iTunes.