[UPDATED] How to Test Your Singular SDK Integration

After you have integrated 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 two main tools for testing your integration: an audit report, which automatically identifies any issues in your integration, and the SDK console, which allows you to manually test the different features you have implement as you implement them.

The following guide will get you started with both tools.

Guide for Developers
Prerequisites Have the Singular SDK or S2S implemented for an app. To use the SDK Console, you will need a mobile device to test with.

 

Automatic Testing: 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:

1

Run an SDK Audit Report

Go to Settings > SDK Console and click Audit your SDK integration in the top right corner.

test1.png

2

Download and Read the Report

Once the report finishes running, you'll be able to download it in CSV format.

The report is a list of issues that have been found in your SDK and S2S integrations. Not all issues are critical, and some may not be relevant for you (because they pertain to SDK features you have chosen not to implement). For more about how the report is built, see How do I read the SDK audit report?

test2.png

3

Fix the Relevant Issues

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

Note: For warning/info type issues, make sure to 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.

See also: Auditing Tool for SDK/S2S Integrations: FAQ

Manual Testing Using the SDK Console

Tips:

  • Use these testing steps in combination with the SDK auditing tool to make sure your SDK/S2S implementation is functioning correctly.
  • You can also use the SDK console to test features one by one as you implement them (before you've completed the entire integration).

For general questions about the SDK console, see the SDK Console FAQ.

1

Add a Test Device

To add a device to the console:

  • In the Singular platform, go to Settings > SDK Console.
  • Click Add Device.

  • Select the platform of the device you are adding, and then select the keyspace (i.e., the type of advertising ID), e.g. IDFA or Google Advertising ID.

  • Input the ID from your device and click Add.

    test3.png

Notes:

  • For iOS devices, we recommend using the IDFV if you have access to it. You can use the IDFA, but then you won't be able to make the console "forget" your device's data (see step 5).
  • Your device's GAID or IDFA should be available in your device's Settings menu. Singular also offers a Device Assist application that you can install on your test devices to help you acquire the device IDs. Download our app for iOS or for Android.
  • See also: Types of Device IDs.
2

Ensure Device Appears in Tracked Devices List

The device has to be in enabled mode (the eye icon on the left should not be disabled) for any events from the device to appear in the Events Log.

You can add a descriptive name for the device in the Device Name column to make sure you don't confuse it with other devices you may be tracking.

test4.png

3

Test Initialization and Sessions

The first thing to test is whether your integration is initializing and sending information to Singular. This already allows Singular to start tracking attribution for this app! To check, look for user sessions in the event log.

To test initialization:

  1. On your device, open the app.
  2. Wait 1-2 minutes.
  3. Look at the event log in the SDK console and make sure it shows a session row for the device:

    test5.png

If this row does not show up, check the user-level logs for the session event. It is possible you opened the app before the SDK console finished processing the registration of the new device.

4

[iOS] Test Apple iAd Referrer

On iOS devices, Singular should be receiving the iAd Attribution data. To validate it, after having added a device to the console and installed the app on it, check the SDK console and confirm that “__iAd_Attribution__” event shows up.

test7.png

Notes:

  • This event shows up soon after the app is installed. To test it on an older device on which the app has been installed for a while, follow the instructions to reset the device and then add the device again to the console and re-install the app on it.
  • If the event does not show up, it is possible the app was opened before the device was completely registered in the SDK console. If you integrated the Singular static library, make sure you are importing iAD.framework (if you are using CocoaPods it is already included).
5

Test Custom User ID

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

  1. Register the device in the SDK console.
  2. Open the app.
  3. 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.
  4. In the next event sent to Singular, expand the event details in the SDK console and check that the details include a value for "custom_user_id".

    test8.png

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 SDK Console.
6

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:

  1. Trigger the event from the app and check that it appears in the event log with the name you gave the event.

    test9.png

  2. If you are sending any additional data with the event, click the event's row in the SDK console to expand the event details, and ensure the data is included in "event_data".

    test10.png

If the event does not show up, it is possible the app was opened before the device was completely registered in the SDK console. Check the attribution logs for the event.

7

Test Revenue

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

  1. 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__".

  2. Click the row to expand it and make sure the currency ("pcc"), amount ("r"), and any other details of the event have been received.

    test11.png

8

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 - Singular's new tracking link technology, launched in 2019. Older customers of Singular may be using Singular's older tracking links (legacy 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. 

test12.png

2. Create a Link to Test

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

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

    test13.gif

3. Test the Link

To test the link:

  1. Make sure the app is installed on your test device.
  2. Email the copied link to your test device.
  3. From the device, open the email and click the link. The app should open and display the intended page or content.

Alternative way to test the link (Android only):

Open a command-line terminal on your computer to trigger a deep-link:

test14.png

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 situation, 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.

9

Test Deferred Deep Linking

  1. To confirm that deferred deep linking is enabled, check the session event in the SDK console.

    test15.png

  2. Set up a test destination and a link as explained above in Test Deep Linking.
  3. Uninstall the app from your test device.
  4. Email the deep link to the device and open it from the device. The link should take you to the app store. After you install the app and open it, you should see the desired page or content.

    test16.gif

10

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 SDK 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:

  1. Using a real device (not an emulator), install the app on the device.
  2. Open the app so that the install is registered.
  3. Uninstall the app. 
  4. 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.