Integrating a Singular SDK: Planning and Prerequisites

The following are required preliminary steps for any Singular SDK integration.

Learn how to plan your SDK integration, register an app for development, create a domain for tracking links, and plan how to test your integration during and after development.

Guide for Business/Marketing Teams

Plan Your SDK Integration

Before you start integrating the Singular SDK, the marketing/business team should answer the following questions. This lets the development team know which SDK features and functionality to enable.

Is this app directed explicitly at children?

Apps for children must comply with Play Store and App Store policies to safeguard children's privacy. We recommend using Singular's Kids Apps SDKs, which help you comply with these policies by not capturing device identifiers.

Will the app handle deep links?

Follow the instructions in Singular Links Prerequisites and then implement a deep link handler in your code as explained in the relevant SDK guide.

Will the app track user events?

Singular can collect data about in-app events to help analyze the performance of your campaigns and measure KPIs. For example, your organization may want to collect data about user logins, registrations, tutorial completions, or leveling up in a gaming app.

Standard Events

Singular supports a variety of standard events. These commonly used events are often supported by ad networks for reporting and optimization. Another advantage is that when you use standard event names, Singular recognizes them automatically and adds them to the Events list without you having to define them manually. We recommend using standard events whenever possible.

For each standard event, you should pass the standard recommended attributes. For example, for a sng_content_view event (the customer views a product), you should pass the attributes sng_attr_content_type, sng_attr_content_id, and sng_attr_content

The list of events sent to Singular (with the accompanying attributes) should be compiled by the UA/marketing/business team based on your Marketing KPIs. The following guides are helpful in building an event strategy:

Important: When integrating a Singular SDK in your app, your developer team may need to use a slightly different version of event/attribute names (all caps, no underlines, etc.) based on the development platform. See lists of event and attribute names for iOS, Android, Unity, React, and Flutter.

Custom Events

If you want to measure events that do not match any of Singular's standard events, you can define your own custom events with custom names.

The development team can use any custom name (maximum of 32 characters). We recommend using names in English for compatibility with any ad network partners that may receive the event from Singular for optimization purposes.

Tip: Send events to Singular only if you need them to be tracked for marketing-related purposes. If an event is not significant as a KPI for campaign performance or user value, that event should not be tracked by Singular.

(iOS) Will the app be implementing SKAdNetwork? 

You can use SDK methods to enable SKAN in Managed Mode (where the conversion value is updated by Singular) or in Manual Mode (where you update the conversion value yourself).

(iOS) Will the app ask the user for permission to share tracking information (ATT)? 

We recommend displaying the ATT prompt because if the user opts in to share their device ID, this helps attribute the install correctly.

If you do display the ATT prompt, you should configure the SDK to delay the initialization of Singular in your app until the user responds.


Register a Development/Testing App

App Bundle Identifier

The same SDK Key and Secret Key is used for production and testing apps. Once testing/production data has been saved in Singular, it cannot be deleted. 

With this in mind, we recommend using a different bundle identifier for your test app to keep data separate from the eventual production app. 

For example, if your production app uses the bundle Identifier com.myapp, you can use for the development stage. You can then change the bundle ID back to the production version before releasing your app in the app stores.

Steps to Register an App

  1. In the Singular platform, go Settings > Apps and click Add New App.
  2. Enter an app name for the development app. We recommend using the Bundle ID.
  3. Select the OS corresponding to the app platform.
  4. Identify the app using Bundle ID option, and enter the development version of your bundle Identifier. Save the app.
  5. For iOS apps: after saving the app, click the arrow next to the app name to view the app details, and toggle the Show Advanced Settings option. Add your TeamID and Scheme. This is required for Universal Links and deep linking.

After you finish developing and testing the app, update the bundle ID to the production version, and let the marketing team add the production app based on the instructions in the App Configuration FAQ.


Create a Link Domain (If You Don't Have One Yet)

Singular Links (Singular tracking links) have the following structure, where [SUBDOMAIN] is chosen by you:


For example, for a campaign that markets an app called Jewel Rush, you can create the domain "". Then you can use it to create tracking links with the following structure:[PARAMETERS]

You can use a single domain for all your links, or you can create several to use for different purposes. In any case, at least one domain is required before you can use Singular Tracking Links. 

The organization's marketing team should be involved in deciding on a link domain, as it will be exposed in marketing campaigns.

When integrating the Singular SDK in iOS apps, you have to add the link domain in the Xcode Associated Domain Settings in the form of:


See also: Singular Links Prerequisites.


Learn How to Test Your Integration

When integrating the Singular SDK/S2S into your app, it's important to make sure it works correctly before you go live with the new version of the app.

Singular offers a selection of tools for testing your integration:

Testing During Implementation:

  • Use the Testing Console, which allows you to manually test the different features you implement, as you implement them in real time.
  • Or use a third-party tool such as Charles Proxy with SSL proxy enabled to verify that Singular data is triggered at the correct time with the correct data points.

Testing After Implementation:

  • Run an SDK audit report to automatically identify any issues in your integration and recommend tried-and-true solutions.
  • Download your user-level data using the Export Logs page. The CSV file shows you all the data sent from your app successfully to Singular. Note that it takes approximately 30 minutes before data is available in this tool.
  • Test your deep links following the instructions in the How to Test Your Singular SDK Integration.
  • Use the Attribution Details API to query the details of the device after your test. It takes approximately 4-6 minutes for attribution data to be available. Learn more.

For more testing tips, see How to Test Your Singular SDK Integration.