Basic SDK integration guide

At a glance: Work with your mobile developer to integrate and install the SDK into Android or iOS apps. Once basic integration tasks are complete, your app is ready for install attribution and in-app event measurement.   

 Related reading

For a complete picture of planning the SDK integration with your app, be sure to read these articles:

• SDK integration overview
• Basic SDK integration guide (this article)
• Additional SDK integration guide

Retrieving the dev key

Before your developer can install and integrate the SDK, you must retrieve the dev key. ZendeskConnect uses the dev key to uniquely identify your account. The dev key is mandatory because it allows the SDK to securely send and retrieve data that belongs to your account.

To retrieve your dev key:

1. In ZendeskConnect, go to Configuration > App Settings. 
2. Copy your dev key, and send it to your mobile developer.

   

3. Provide your mobile developer with the instructions to install and integrate the SDK.

Attribution

The SDK collects identifiers for attribution purposes. To ensure that installs are recorded and attributed correctly, review and follow these guidelines. 

All platforms

Unique identifier for installs

An ZendeskConnect ID is automatically created for every new app install. No action is required by the marketer.

You can use this identifier to perform the following actions:

• Send server-to-server in-app events.
• Match the ZendeskConnect ID with user records in your backend systems.
• Download the raw data in-app event report and use appsflyer_id to analyze user behavior and journeys.

Integrate unique identifiers from your BI system with ZendeskConnect

Set your own Customer user ID (CUID) in the ZendeskConnect SDK to cross-reference the unique ID from your BI system with the ZendeskConnect ID and other identifiers. The CUID is available in ZendeskConnect raw data reports. You can also use it in postback APIs for cross-referencing with your internal IDs. 

See developer instructions for implementing CUID.

Android only

The following sections describe attribution considerations for Google Play Store or third-party app stores.

Attribute apps published on Google Play 

Google Play Install Referrer

The Google Play Install Referrer API improves attribution accuracy, protects from install fraud, and allows secure retrieval of referral data from Google Play (for example, the app's version at the time when the app was first installed). 

It is recommended that you provide your developer with instructions to add the Google Play Install Referrer API. 

GAID

Starting with SDK V4.8.0, ZendeskConnect automatically collects this device identifier.

Attribute devices in third-party app stores

With ZendeskConnect, you can attribute installs originating from third-party app stores, such as Amazon, Opera, GetJar, Baidu, and Huawei. This allows you to promote your apps and reach larger audiences in markets where Google Play is not available.

The SDK uses the following methods to attribute devices in third-party app stores:

• IMEI or Android ID: The SDK doesn't automatically collect the IMEI or Android ID. However, if there is a need to collect these identifiers (for example, for apps in the Chinese domestic market) your developer can implement one of the following collection types:
  • Manual collection: The app passes the IMEI or Android ID to the SDK (using the setImeiData or setAndroidIdData API). The SDK sends the data to ZendeskConnect servers. 
  • Opt-in to device ID collection: Forces the SDK to collect the IMEI or Android ID. 
• OAID: Attributes installs from third-party Android app stores. For more information, see the guide to implementing OAID.

iOS only

The following sections include important information about support for iOS 14+ devices.

Configure App Tracking Transparency (ATT) support

Background

Starting with iOS 14.5, IDFA collection requires user consent. Practically, it means IDFA access is governed by the App Tracking Transparency (ATT) framework. On iOS 14+ devices, the SDK uses the ATT framework to obtain access to the device IDFA. 

For an introduction to ATT, see ATT principles.

When attribution occurs using IDFA, it's important IDFA is sent on the first launch. For this reason, the SDK provides the waitForATTUserAuthorization utility.

waitForATTUserAuthorization overview

 Important!

Don't call waitForATTUserAuthorization if you don't intend to invoke the ATT prompt.

waitForATTUserAuthorization enables you to configure how long the SDK should defer and wait for ATT status before sending data to the ZendeskConnect servers.

When a user launches the app, ATT status is notDetermined. During the waitForATTUserAuthorization timeout, the SDK queues the launch event and consecutive in-app events in-memory, similar to the way in which offline events are recorded:

• If the user consents to the ATT prompt (IDFA collection):
  • The SDK adds the IDFA to cached events.
  • The SDK starts and sends cached events with IDFA (without waiting for the timeout to end).
• If the user declines the ATT prompt: The SDK starts and sends cached events without IDFA (without waiting for the timeout to end).
• If the timeout ends and ATT status remains notDetermined: The SDK starts and sends cached events without IDFA.

Considerations

• Calling requestTrackingAuthorization without setting waitForATTUserAuthorization will result in launches and events being sent without IDFA for iOS 14+ devices.
• If the user moves the app to the background during the timeout:
  • The timer pauses until the app returns to the foreground.
  • Events are cached in-memory.
• If the user shuts down the app, it is killed during the timeout:
  • The timer is restarted on the next app launch.
  • Cached events are lost.

Customize ATT consent dialog

You can customize the ATT prompt. A message that clearly states the purpose of the request could help increase the opt-in rates for users.

Consider the following when creating your message:

• Use wording that best explains to your users why the app is asking for user consent.
• Inform users about how their data will be used. Learn more about user privacy and data use.

Once your message is complete, provide your developer with the text and implementation instructions.

See some external examples of ATT prompts.

Support for SKAN attribution

 Note

To fully support SKAN attribution, upgrade to iOS SDK V6.2.3+.

SKAN is a class used by iOS to validate advertiser-driven app installations. The app install validation process involves the source app and the advertised app. 

A source app is an app that participates in ad campaigns by displaying ads from an ad network. Configuring your app to display ads is not within the scope of the ZendeskConnect SDK. To configure, follow the Apple instructions.

For the advertised app (the app with the ZendeskConnect SDK), the ZendeskConnect SKAN solution uses SKAN to provide the attribution postback while ZendeskConnect collects, translates, and aggregates the data while maintaining user privacy. When the app is launched for the first time, the ZendeskConnect platform uses the configuration set by the marketer to instruct the SDK how to set the SKAN conversion value.

To use the SKAN solution:

• The marketer needs to configure SKAN measurement in ZendeskConnect. The developer does not have to perform any tasks.
• The ZendeskConnect SDK automatically calls the necessary SKAN APIs.
• Make sure to disable SKAN calls in other SDKs if you rely on ZendeskConnect for SKAN attribution.
• There is no other action or registration process required by either the developer or the marketer in the App Store. 

To disable SKAN attribution, instruct your developer to disable it in the SDK. 

Recording in-app events

In-app events (IAE) provide insight into what is happening in your app. Recording in-app events helps you measure KPIs like Return on Investment (ROI) and Lifetime Value (LTV). We recommend taking the time to define the events that you want to record.

Once you determine the in-app events you want to measure, send the event names and parameters to your developer, and include a link to the implementation instructions. 

To learn more about in-app events, see our Rich in-app events guide.

All platforms

Record revenue

You can send revenue with any in-app event. Make sure you use the af_revenue parameter to include revenue. It is the only event parameter that ZendeskConnect counts as real revenue on the dashboard and in raw data reports. Learn more.

For developer instructions, see logging revenue.

Validate in-app purchases

The ZendeskConnect SDK provides server verification for in-app purchases. Validating an in-app purchase automatically sends an in-app purchase event to ZendeskConnect. Sending this event yourself creates duplicate event reporting.

Industry verticals

See our list of recommended in-app events per vertical, for example, travel, gaming, or eCommerce.

Deep linking with OneLink

OneLink is the ZendeskConnect solution for multi-platform attribution, redirection, and deep linking.

All platforms

Device detection and redirection

For users without your app installed, OneLink detects the device type and redirects them to the correct destination (for example, Google Play, Apple App Store, third-party app store, or web page). This is based on your OneLink template settings. Learn more

Deep linking

For users with your app installed, OneLink opens the app. In addition to opening the app, you can also deep link users to a specific activity or page within the app. This requires your developer to implement Unified Deep Linking (UDL).

Note:

• UDL requires SDK V6.1+.
• Customers already using OneLink for deep linking may be using the legacy method, instead of UDL.

See our guide on setting up deep linking with OneLink.

Deferred deep linking

For users without your app installed, OneLink detects the device type and redirects them to the correct destination: Google Play, Apple App Store, third-party app store, or web page. Once the user launches the app, you can use deferred deep linking to redirect them to a specific activity or page within the app.

This requires your developer to implement Unified Deep Linking (UDL).

Note:

• UDL requires SDK V6.1+.
• Customers already using OneLink for deferred deep linking might be using the legacy method, instead of UDL.

See our guide on setting up deferred deep linking with OneLink.

Accessing attribution and deep linking data

The following table describes the available methods for retrieving attribution and deep linking data:

Method	Who is involved?	Return results	Retrieval method	Attribution data	Deep linking data	Availability
Push API	Marketer Back-end developer	Typically within minutes	Backend	Y	N	Premium
Get conversion data (GCD)	Marketer Mobile  developer See developer documentation	Up to 5 seconds	SDK	Y	Y	All accounts
Unified Deep Linking (UDL)	Marketer Mobile developer See developer documentation	Up to 1 second	SDK	N	Y	All accounts
Pull API	Marketer Back-end developer	Periodic (not real-time). You can schedule raw-data report downloads.	Backend	Y	Y	Premium for raw-data reports

Note the following for iOS 14.5+ non-consenting users:

• When using UDL for paid and owned media, deep linking data is available.
• When using GCD for paid media, the data is limited and does not include attribution and deep linking details.

 Tip

We recommend the following:

• Use Push API to retrieve attribution data and send it to your servers for further processing. This method waits for the data to become available, and therefore is highly accurate and close to real-time. GCD returns data in real-time, but may be inaccurate when final attribution decisions are determined after more than 5 seconds.
• Use Pull API to periodically (for example, daily) supplement real-time attribution data, and to compensate for any communication errors that might occur.

Testing your SDK integration

Once the SDK integration is complete, you can go to the ZendeskConnect dashboard, and from the SDK Integration Tests page, test organic and non-organic installs, in-app events, and deep linking (retargeting). This ensures that installs and in-app events are recorded and attributed correctly.

If you need your developer to test the SDK integration, add the developer as a team member in your account, so they can access the dashboard. 

For testing scenarios and instructions, see SDK integration testing.