After integrating the Singular SDK into your app or building a server-to-server integration, it is essential to verify that Singular receives data before you go live with the new version.

Guide for	Developers
Prerequisites	Implement the Singular SDK or set up the server-to-server (S2S) integration for your app. Ensure you have a mobile device for testing if you plan to use the Testing Console.

Singular provides three main tools for testing your integration:

Testing Console: Test features in real-time as you implement them.
Export Logs: Download user-level data with at least a one-hour delay.
Audit Report: Automatically identifies any issues in your integration.

Using the Testing Console

The Testing Console lets you stream live, real-time data by adding and selecting a test device. Note that it does not provide historical reports. To get started, ensure you have the following:

A clean test device: Use a device that has never had the test application installed.
A list of events and attributes to test: Prepare the events and attributes you plan to verify.
For iOS: Be aware of whether the App Tracking Transparency (ATT) prompt will appear, as this will determine if you use the IDFV or IDFA identifier for testing.

Add a test device

To add a device to the Testing Console:

In the Singular platform, go to Developer Tools > Testing Console.
Click Add Device.
Provide your Device Type. For Android, when available, we recommend Google Advertising ID (GAID/aifa), AppSetID (asid) or AndroidID (andi) in that order. For iOS devices, we recommend using the IDFA when available.

Provide your Device ID.

Capturing the device ID

For Android, we advise using the Google Advertising ID (GAID/aifa). The Singular Device Assist app (Android) can help you find it.

The aifa is also found in the Android LogCat when logging for the Singular config is enabled.

SingularConfig config = new SingularConfig(SdkKey, SdkSecret)
 .withLoggingEnabled()
 .withLogLevel(1);

Sample LogCat output:

2023-06-01 15:48:32.224 27442-27560/com.singular.test D/Singular: DeviceInfo [worker] - andi : 8868adc2f7ffffff

2023-06-01 15:48:32.224 27442-27560/com.singular.test D/Singular: DeviceInfo [worker] - asid : 12dc3652-5e46-f2bb-a93a-b3c092ffffff

2023-06-01 15:48:32.224 27442-27560/com.singular.test D/Singular: DeviceInfo [worker] - aifa : 3bbc76b0-cebb-4a9f-b6ec-10ca1affffff

For iOS, you can use IDFA when the ATT framework is in place and tracking is permitted. Ensure that the Wait For Tracking Authorization With Timeout Interval is also implemented. For all other instances, use IDFV.

IDFA can be captured using one of the methods listed below:

Use the Singular Device Assist app (iOS) from the App Store. Make sure to give permission for tracking.
Logging the IDFA in the debug console of Xcode

//Example in Swift
print("IDFA", ASIdentifierManager.shared().advertisingIdentifier.uuidString)
                
//Example in Objective-C
NSString *IDFA = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
NSLog(@"IDFA: %@", IDFA);

IDFV can be captured in the debug console of Xcode.

//Example in Swift
print("IDFV", UIDevice.current.identifierForVendor!.uuidString)
                
//Example in Objective-C
NSString *IDFV = [[[UIDevice currentDevice] identifierForVendor] UUIDString];
NSLog(@"IDFV: %@", IDFV);

Add a distinct Device Name and click Save Device.

Test Initialization

The first thing to test is whether your SDK integration is initialized successfully and is able to send information to Singular (ie. the event you are looking for is called: session). This allows Singular to start tracking attribution for this app!

To test initialization:

In the Events Log, select your device name from the Devices dropdown. Look for the 🟢 Live indicator.
Initialize the app from your testing platform / open the app.
When you see a session event, you've successfully initialized the Singular SDK.

How do I read the Events Log in the Testing Console?

After you've registered a device and sent some events, the events start appearing in the event log on the Testing Console page.

Click on a row to show the full details of the event as sent from the app.

Why are no events showing up in the Testing Console Events Log?

If you have registered a test device and are following the guide to test your SDK integration, but no rows are showing up in the Events Log, double-check the following:

The Testing Console only shows events live, i.e. when you are on the page with a selected device and the 🟢 Live indicator. It does not look for historical events from the device. If you fire events before selecting a device it will not appear in the console.
Make sure you opened the app on the test device (to see a user session).
Make sure you created some in-app events (if you want to test your events).
Double check that you have entered the correct device id
Double check that you are using the correct device id type (for ios, if you didn't see an ATT prompt you cannot use IDFA)

Why is the _InstallReferrer event missing when testing an app with Singular SDK 12.0.0 and above?

Starting from Singular SDK 12.0.0, you don't need to test the _InstallReferrer event. Once your app is pushed to the store, our SDK will place the _InstallReferrer data in the first session. You only need to see if the session appears in the Testing Console.

If you are using older versions of the Android SDK, you will still need to check the _InstallReferrer event in the Testing Console.

How do I delete/remove a device from the console?

Deleting a Device

To delete a device from the Tracking List, click the Edit icon, and on the shelf that appears, click Delete Device. This will clear all event logs from the page, and Singular will delete internal data about the device's attribution.

How do I reset a device and clear its attribution information so I can use it to test install attribution again?

If you want to re-test your SDK integration again with the same device, you have to remove all locally cached data from the device, in addition to clearing the device's attribution in the Singular platform.

Steps for Android Devices

Close the app and confirm that it is not running (use Force Stop from the Settings menu if you have the option).
Go to the Settings menu by tapping the wheel icon in your notification window or in the Apps menu.
Go to Apps, select the app you are testing, long press on the app and select App Info.
Select Storage and then select Clear Cache and Clear Data.
In the Singular Testing Console, select the device from the dropdown and click the Edit (Pencil) icon. On the shelf that opens, click Delete Device to have our system delete this device attribution.

Steps for iOS Devices

Close the app and then uninstall.
Open the Testing Console, find your device in the dropdown, and click the Edit icon. On the shelf that opens, click Delete Device to have our system delete this device attribution.

Tip: Testing With Re-engagement Inactivity Windows

The inactivity window is a setting that determines how long the user has to be inactive before they are eligible for re-engagement attribution. If you are testing re-engagement attribution prior to launching campaigns, an inactivity window would make it harder for you. This is why test devices (devices that have been added to the Testing Console and have the eye icon enabled) are exempted from the inactivity window.

I’m testing with IDFA and I just can't get iOS to show up in the testing console. What do I do?

Double check that your IDFA is correct. You can do this several ways:

Use the Singular Use the Singular Device Assist app (iOS) from the App Store. Make sure to give permission for tracking.
Logging the IDFA in the debug console of Xcode
If you already did a test more than an hour ago you can go to export logs and see if there were any events captured. You can pull the IDFA/IDFV from export logs. When pulling from the export log try adding “App Tracking Transparency status” as well to the report. 0 - Undetermined, means the ATT prompt was not shown (usually because the general settings are blocking it or there was a timeout). You can read more here

Other things you can check:

Check Device Settings: Ensure that the device's advertising identifier (IDFA) has not been limited. Go to Settings Privacy Tracking on the device and make sure that the "Allow Apps to Request to Track" option is enabled. Make sure that you saw that ATT prompt while testing. If you didn’t see it, then we are not tracking the IDFA.
Reset Advertising Identifier: If the device has been used for testing before, reset the advertising identifier. Go to Settings Privacy Tracking and reset the IDFA.
Correct Implementation: Verify that the Singular SDK has been correctly integrated into your app and that you are using the latest version of the SDK.
Wait for Data to Appear: There shouldn’t really be a delayin data appearing in the testing console. If you are waiting for longer than one minute, something hasn’t been set up correctly.
Review SDK Initialization: Confirm that the Singular SDK is initialized correctly in your app's code, particularly in the AppDelegate or SceneDelegate depending on your app's architecture.
Check for Errors: Look for any errors in the Xcode console that might indicate issues with the SDK initialization or event tracking.

If you have followed these steps and the issue persists, it may be necessary to review the detailed integration guide or check with the Singular integration engineer for further assistance.

Test specific features

Test Custom User ID

If your SDK integration sends a custom user ID to Singular, here's how to test it.

Register the device in the Testing Console.
Open the app.
If needed, in your app, trigger an action that sends the user ID (such as logging in). The nature of the action depends on your implementation.
In the next event sent to Singular, expand the event details in the Testing Console and check that the details include a value for "custom_user_id".

If the user ID does not show up:

Check that the method that sets the user ID is actually being called in your app when you want it to be.
You may want to add a Singular SDK event and call it "setting custom user id" so that the event shows up in the Testing Console.

Test Events

If you've implemented event tracking or revenue tracking in your SDK integration, follow the instructions below to test them.

For more about events, see:

For every event you've implemented in your SDK integration:

Trigger the event from the app and check that it appears in the testing console log with the name you gave the event.
If you are sending any additional data with the event, click the event's row in the Testing Console to expand the event details, and ensure the data is included in "Event Data".

If the event does not show up, it is possible the app was opened before the device was completely registered in the Testing Console. Check the export logs for the event.

Test Revenue

For each type of revenue event you've implemented in your SDK integration:

Trigger the revenue event in the app and check the events log. A row should appear with the event name.

Note: If you didn't give the event a custom name, it receives the default name for revenue events, "__iap__".
Click the row to expand it and make sure the currency ("pcc"), amount ("r"), and any other details of the event have been received.

Test Deep Linking

If you've implemented deep linking in your SDK integration, follow the instructions below to test your deep linking functionality.

Note: This article assumes your organization is using Singular Links.

1. Set Up a Test Destination

In the Singular platform, go to Settings > Apps, find the app, and add a deep link destination.

The destination should be one of the deep link destinations that the handler code in your SDK integration can recognize and handle.

2. Create a Link to Test

Now that you have a destination to link to, you can create a deep link.

Go to Attribution > Manage Links and select the app from the sidebar.
Click Create Link.
Under Link Type, select "Custom Source", and under Source Name, select "Email".
Give the link a name.
Click the Link Settings and Redirects section to expand it.
Select the destination you just created in the Deep Link dropdown list.
In the Fallback Destination for Other Platforms text box, enter a website URL.
Click Generate and copy the link from the Click-Through Tracking Link field.

3. Test the Link

To test the link:

Make sure the app is installed on your test device.
Email the copied link to your test device.
From the device, open the email and click the link. The app should open and display the intended page or content.
If you are using the SDK Testing Console during the test, you should see the Deep Link in the Session arguments:

Alternative way to test the link (Android only):

Testing Android deep links using ADB (Android Debug Bridge) is a common practice to verify that your app handles deep links correctly. Here's a step-by-step guide on how to set up and use ADB for deep link testing:

Prerequisites

Install ADB: Make sure you have ADB installed. It’s included in the Android SDK platform tools, which can be downloaded from the Android developer website.
Enable Developer Options: On your Android device, enable Developer Options and USB debugging.
Go to Settings > About phone and tap Build number seven times to enable Developer Options.
Go to Settings > Developer options and enable USB debugging.
Connect Your Device: Connect your Android device to your computer via USB. Ensure that it is recognized by ADB by running:
From the terminal on your computer run:
```
adb devices
```
This command should list your device.

Testing Deep Links with ADB

Use ADB to Send the Deep Link: To test a deep link, use the adb shell am start command. This command simulates clicking a deep link in a browser or another app.
The general syntax is:
```
adb shell am start -W -a android.intent.action.VIEW -d "your_deep_link_url"
```

From the terminal on your computer trigger the link:

adb shell am start -W -a android.intent.action.VIEW -d "https://seteam.sng.link/Bnuq6/i428?_dl=androidkotlinapplication%3A%2F%2Fmy_deeplink"

Troubleshooting

"When my app is already running, a deep link opens a new instance of the app instead of switching to the existing one." To avoid this, edit your manifest file and add the following to your activity:

android:launchMode="singleTask"

See Google's <activity> documentation for more information about launchMode options.

Test Deferred Deep Linking

To confirm that deferred deep linking is enabled:

Check the session event in the Testing Console.
Set up a test destination and a link as explained above in Test Deep Linking.
Uninstall the app from your test device.
Reset your device Advertising Identifier.
Add the new Identifier to the Testing Console.
Email the deep link to the device and click on the link.
The link should take you to the app store. Note: If you are testing on a local build, do not install the Store version, instead side load the App from Android Studio or Xcode. After you install the app and open it, you should see the desired page or content.
If using the SDK Console for the test, you should find the deferred deep link value in the first session event.

Test Uninstall Tracking

If you've implemented uninstall tracking in your SDK integration, follow the instructions below to test it.

Testing uninstall tracking is more complicated than testing other SDK functions, because Singular depends on Google/iOS services to report the uninstall, and the process takes some time. You can't see the uninstall event in the Singular platform in real time, and you can't use the Testing Console for it.

Before you test, make sure that you are sending your FCM/APNS token to Singular (see Android SDK: Tracking Uninstalls and iOS SDK: Tracking Uninstalls).

Also, double-check that you have entered your FCM Server Key (for Android) or your iOS Push Certificate in the App Configuration page.

To test uninstall tracking:

Using a real device (not an emulator), install the app on the device.
Open the app so that the install is registered.
Uninstall the app.
To check if Singular has received the uninstall event, you have several options:
- Export the attribution logs (event logs) and find the uninstall event. It may take a couple of days for it to show up in the logs.
- If you have set up postbacks to be sent to your internal BI system, you can receive a postback about the uninstall.
- You can contact Singular support or your Customer Success Manager to help you validate uninstall tracking.

Note: While you are waiting to validate the uninstall event, don't reset the device ID and don't reinstall the app.

Note: The testing console doesn't support iOS TestFlight apps. A TestFlight build resets the IDFV on every app launch and live events cannot be captured.

Using the Export Logs

You can also use the Attribution > Export Logs to verify test results with a delay. The Export Logs feature allows you to manually download user-level data such as Conversions (installs), Events, etc.

Best practices:

Before obtaining the data, double-check that the Date, App, and site are selected appropriately.
Data in the export logs is ~3 hours behind.
For more help, see this FAQ.

Running an SDK Audit

Singular offers an SDK audit report that tests your SDK and S2S integrations to see if they are correctly implemented. The audit outputs a list of all the issues that it finds, with tips for how to solve them. To use the SDK audit report:

Run an SDK audit report

Go to Developer Tools > Testing Console and click Run Audit in the top right corner.

Download the report and fix the relevant issues

Once the report finishes running, you can download it in CSV format.

The report is a list of issues found in your SDK and S2S integrations. Not all issues are critical or relevant, depending on which features you've implemented.

Go over the issues in the report and fix them according to the tips in the Error Description field.

For warning/info type issues: Check the Validation Name and see whether this is an optional SDK feature that you have chosen not to implement, such as deferred deep linking (DDL). If so, you can ignore the error message.

How does the SDK audit work and what data does it run on?

The SDK audit looks at data received from your apps in the last 3 days. It checks whether the data looks as expected, e.g.:

Whether the app is reporting user sessions (this is the most basic functionality of an SDK/S2S integration and is what enables Singular to track attribution)
Whether the app is reporting in-app events and revenue
Whether revenue is reported using best practices
Whether deferred deep linking is enabled

How do I read the SDK audit report?

Screen_Shot_2021-11-11_at_18.28.27.png

The report is a list of issues that have been found in your SDK and S2S integrations.

Column	Description
App Name	The name of the app as configured in Singular.
App Bundle	The app bundle as configured in Singular, e.g., com.example.appname.
Platform	iOS, Android, or Amazon.
App Version	The app version number, if any.
Validation Name	The area of the integration in which an issue has been found, e.g., "Custom user ID" or "Revenue events".
Type	The severity of the issue: Error: This issue prevents the integration from working and you have to fix it before you go live with the app. For example, Singular is not receiving user sessions from the app. Without user sessions, we can't perform attribution. Warning: The integration can work without this but you should fix it if you want to follow best practices and get the most from the Singular attribution tracker. For example, your app is not sending a custom user ID. The custom user ID is an optional feature but highly recommended. Info: This issue concerns optional functionality that you may have chosen not to implement in your integration. For example, deferred deep linking (DDL) is not enabled in your app. DDL may simply not be relevant to your marketing strategy.
Error Description	More information about the issue and how you can fix it.

How to Test Your Singular SDK Integration