# 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](https://developers.google.com/app-conversion-tracking/api/request-response-specs) 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](https://developers.google.com/app-conversion-tracking/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](https://developer.android.com/google/play/installreferrer/igetinstallreferrerservice)
`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 replaced by another more recent value.
The `gclid` value should 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 be passed via
the **`gclid`** conversion request field, and
the deeplink `gbraid` value should be passed via
the **`gbraid`** conversion 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](https://developer.android.com/google/play/installreferrer/igetinstallreferrerservice)
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 recent 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 **`gclid`** conversion request field, and
the deeplink `gbraid` 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
       
```

> [!NOTE]
> **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](https://developer.apple.com/app-store/user-privacy-and-data-use/)
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](https://developers.google.com/app-conversion-tracking/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.
Each value should be stored for 180 days, or
until replaced by another more recent value.
The `gclid` value should 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]
> **Note:** `gbraid` cannot be leveraged in Install scenarios since users are first redirected to iTunes.