# ID Sync

## Recommended integration: ID Sync

Chartbeat allows customers to send through custom data and fields in the form of a key value pair to link to other products or data sets in your ecosystem. 

For example, with ID Sync you can parse your Google Analytics ID from your Google Analytics cookie and link it to our ID Sync variable in your Chartbeat code, then your Datastream data will contain your Charbeat data along with your GA ID as an additional data column in your feed. This data can now be easily mapped to and queried with all your GA data sources to get a comprehensive overview of all your data and help your [**Data Science and BI teams can create custom analyses** ](https://docs.chartbeat.com/datastream/getting-started/use-cases#for-business-intelligence-and-data-analyst-teams)that help inform company-wide goals.

Some of the common use cases of ID Sync include:

* **Parse IDs from other products:** Google Analytics, Adobe Analytics, Data Management Platforms (DMPs), content management system (CMS), Ad platforms etc.
* **Customer IDs:** You can send us a unique (defined in your system) customer identifier such as a hashed email ID or subscriber ID.
* **Page IDs:** For websites that have unique Page IDs, this field would help you track sessions across different pages and match it with your CMS data. 

With ID Sync, website owners can populate their Datastream feed with unlimited custom ID values via a few extra lines of JavaScript in our tracking snippet for standard websites. 

{% hint style="info" %}
**Note:** this additional JavaScript tracking configuration variable is supported by our tracking integration for standard websites and our native SDKs. It is not currently supported in our AMP integrations.
{% endhint %}

When you send Chartbeat custom data through ID Sync, this information will appear in your Datastream data feed files as `id_sync`. If using one of our reserved keys, that data will appear under `ga_client_id` or `login_id` ([see below](#reserved-keys-1)) . 

### Implementation for standard website

Adding custom metadata through ID Sync is simple. Within either the [**initial setup code**](https://docs.chartbeat.com/cbp/tracking/standard-websites/our-javascript) for the Chartbeat tracker or in the `loadChartbeat()` function, specify the following:

```javascript
_sf_async_config.idSync = _sf_async_config.idSync || {}; 
_sf_async_config.idSync.KEY_NAME = VALUE;
```

Note that the `idSync` variable specified above is a JavaScript Object, not a string, so be sure to specify it as such.

### Implementation for native app SDKs

If using our [Android](https://docs.chartbeat.com/cbp/tracking/mobile-app-sdks/android-sdk) or [iOS SDK](https://docs.chartbeat.com/cbp/tracking/mobile-app-sdks/ios-sdk), please follow the instructions below to send custom data through ID Sync.

#### Android SDK

In order to send custom data you will have to instantiate HashMap and add key pair values. 

**Java**:

```
private void setCustomData(){
  final HashMap<String, String> customData = new HashMap<>();
  customData.put("ga", "286243809.1415748215");
  customData.put("l", "login-id-123");
  customData.put("customKey1", "customValue1");
  Tracker.setCustomData(customData);
}
```

*Note*:  `ga` and `l` are reserved keys ([see below](https://docs.chartbeat.com/datastream/implement-tracking/id-sync#reserved-keys)).

#### iOS SDK <a href="#reserved-keys" id="reserved-keys"></a>

```
CBTracker.shared().idSync = ["ga":"286243809.1415748215", "l":"login-id-123","customKey1":"customValue1"]
```

*Note*:  `ga` and `l` are reserved keys ([see below](https://docs.chartbeat.com/datastream/implement-tracking/id-sync#reserved-keys)).

### Reserved Keys <a href="#reserved-keys" id="reserved-keys"></a>

There are two keys in the `idSync` object which Chartbeat reserves for special use:

* **Login ID** (`idSync.l`) - A way to uniquely identify a user. You can set this to any value you would like, but we recommend you use a persistent ID that will not change. This data will be accessible via the `login_id` column of your Datastream feed files.
* **Google Analytics Client ID** (`idSync.ga`) - This user’s [**Google Analytics Client ID**](https://developers.google.com/analytics/devguides/collection/analyticsjs/cookies-user-id). Used by Google Analytics to identify if different browser sessions came from the same user. This data will be accessible via the `ga_client_id` column of your Datastream feed files.

#### Getting the GA Client ID from the cookie <a href="#getting-the-ga-client-id-from-the-cookie" id="getting-the-ga-client-id-from-the-cookie"></a>

Google recommends that you not directly access the cookie analytics.js sets, as the cookie format might change in the future. Instead, you should use the readyCallback to wait until analytics.js is loaded, and then get the clientId value stored on the tracker.

```javascript
ga(function(tracker) { 
   _sf_async_config.idSync.ga = tracker.get('clientId');
});
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chartbeat.com/datastream/implement-tracking/id-sync.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.