Testing & Troubleshooting

When you first implement the TUNE SDK, it's always a good idea to make sure that the SDK is properly setup to log user interactions within your mobile app. First confirm that the TUNE SDK is successfully integrated before you update your mobile app in its respective app store. You can save an enormous amount of time, resources, and frustration by testing that all functions are operational before updating your mobile app for the app store.

Android SDK Implementation Troubleshooting

iOS SDK Implementation Troubleshooting

Creating a Test Profile

When you first implement Attribution Analytics as your mobile app attribution and analytics solution, make sure that the SDK is set up properly to log user interaction with your mobile app. Using test profiles, you can use a single device to:

  • Log duplicate installs for testing
  • Log duplicate events for testing
  • Log multiple attributions using a single click

👍

Tip

Depending on your Frequency Capping for Events settings for an event, setting up a test profile for your device enables Attribution Analytics to test the logging of additional events without enforcing this setting.

Adding a Test Profile

Before you start testing your mobile app, first set up a test profile for your test mobile device because TUNE only allows one install per mobile app per unique device ever. By setting up a test profile, you can test for proper functionality with the same device.

🚧

Deprecation Notice

We have deprecated support for Windows devices. Contact our support team with any questions related to this change.

To set up a test profile:

  1. In the main navigation, under Applications, expand Testing, and then click Test Profiles.
  2. On the Test Profiles page (on the right side), in the upper-right corner, click Create Test Profile.
  3. In the Create Test Profile dialog box, complete the following fields.
    • Test Profile Name [REQUIRED]
      • Enter a name for the test profile. If different individuals are testing, consider using their names.
    • Test Profile Type [REQUIRED]
      • Click the appropriate platform that your mobile app runs on: iOS, Android, Fire, or Other.
    • Device Identifier(s) of Choice [REQUIRED]
      • Depending on the platform selected, provide at least one identifier for your test device. You don't need to create a test profile for each supported platform because you can simply provide device identifiers for both platforms simultaneously in one test profile. Installs associated with a test profile have the same tracking ID.

After you add a Test Profile, TUNE starts to compare each click, install, and/or event request with the test profiles. If one of the identifiers from the Test Profile matches the identifiers in the request, then TUNE handles it according to the status specified for the Test Profile: Active – process all conversions; or Inactive – reject all conversions.

Including Test Data in Reporting

After you set up a test profile in Attribution Analytics and run a test (for example, perform a mobile app install on your test device), you must include test data in your reports (else you will not see the test install event because by default, Attribution Analytics excludes test data from reporting). To include test data in your reports:

  1. In the navigation, under the Reporting section, click the desired type of report (for example, Actuals, Cohort, Retention, or Logs).
  2. On the report page, next to the date time in the upper-left corner, click Edit.
  3. In the parameters and filters panel, scroll down to the Filter section at the bottom, remove the Test Data: Exclude filter, and then click Apply.

Things to Keep in Mind

  1. Android Test Profile – You must specify a device identifier (such as Android ID, Device ID, or Google Ad ID) to create the test profile. When creating your TUNE links, append the identifier used to create the test profile to the TUNE link. We recommend using the Google Advertising ID (AID) because eventually Android ID and Device ID will likely be deprecated. For example:

    1.api-01.com/serve?action=click&publisher_id=XXXXXX&site_id=XXXXXXX&offer_id=XXXXXX&google_aid=AAAAAA-BBBB-CCCC-11111-2222222222222
    
  2. iOS Test Profile – You must specify either the iOS Identifier for Advertisers (IFA) or Identifier for Vendors (IFV) to create the test profile. If you use IFA, then your app needs to explicitly set the IFA in the iOS SDK. When creating your TUNE links, append the "ios_ifa" used to create the test profile to the TUNE link. For example:

    1.api-01.com/serve?action=click&publisher_id=XXXXX&site_id=XXXXXX&offer_id=XXXXXX&ios_ifa=12345678-1234-1234-1234-123456789012
    

    📘

    Note

    While you can use IFA for attribution but not IFV, you can use IFV with a test profile because the IFV value remains the same from test to test, and always collected and included with each request to log events (such as an install or in-app event). If your SDK implementation is not set up to collect IFA, then use IFV or Device IP to set up a test profile.

  3. All Platforms Test Profile – To set up a test profile that works on multiple mobile platforms, you must specify either the TUNE ID (generated by the SDK), User ID (specified by advertiser), or Device IP. If your SDK implementation includes your own User ID with each logged event, then you can include this value and it works as a device identifier (such as iOS IFA, or Google AID).

    Our SDKs also generate an ID known as the TUNE ID, which you use for logging post-install events on the server side. For information about loading the Event Request URL (server-side or client-side), please visit measuring events server-side after the install.

    If you want to set all devices for an office into testing mode, then create a Test Profile and enter the IP address for your office. TUNE treats all requests from the IP address as though they belong to the same Test Profile.

    To look up the IP address for your location:

    1. Connect to your Wi-Fi network

    2. Open a browser window and visit whatismyip.com

    3. Create a test profile with only the IP address that appears in your browser

    4. Test Profile Statuses – You can set one of two status levels for Test Profiles:

      • Inactive – Reject all conversions from these devices.
      • Active – Process all conversions and don’t check for duplicate installs/events.

    📘

    Note

    TUNE logs update events (from devices with an active Test Profile) as installs.

  4. Global Test Profiles – If you're a publishing partner or ad network who works with multiple TUNE clients, then you can set up global test profiles that work for all clients using the alpha publisher interface.

Debugging Tune SDK Integration Using mitmproxy

mitmproxy Overview

mitmproxy (man-in-the-middle) HTTP proxy allows you to view the network request-response contents being sent over the network. This technique comes in handy when debugging Tune SDK integration and to ensure that an app downloaded from the App Store fires the expected network requests. On Mac OS X, mitmproxy provides a great free option to do just that.

Install mitmproxy on macOS

Install from command-line (Terminal) using pip.

$ pip install mitmproxy

OR

  • Download latest mitmproxy
  • Extract the downloaded file, which should contain the mitmproxy executable

You can find more information at mitmproxy.org.

Find Out the IP Address of Your Mac

  1. Open System Preferences and go to Network.
  2. Select the network interface you're currently using (i.e. Wi-Fi, Thunderbolt Ethernet, etc.) on the left side of the Network preference window.
  3. Look for the interface's IP address on the right side. Typically this will look like 192.168.x.x, 10.x.x.x, or 172.16.x.x - 172.31.x.x. This will be the IP address to use for your proxy.
In this screenshot, the system's IP address is 192.168.1.76In this screenshot, the system's IP address is 192.168.1.76

In this screenshot, the system's IP address is 192.168.1.76

Run mitmproxy

  1. Open a Terminal window

  2. Run the appropriate command based on your install method:

    • If you used the first method (using pip) to install, then mitmproxy should be available anywhere and can be run as follows:

      $ mitmproxy
      
    • If using the second method of downloaded archive, you should open the folder that contains the mitmproxy module:

      $ cd /path/to/download
      $ ./mitmproxy
      

Add Ignore-Pattern

By default, mitmproxy intercepts all network requests. To intercept only some specific requests, set an ignore-pattern in mitmproxy. Requests that don’t match the pattern will bypass mitmproxy. Adding an ignore-pattern is especially important if your app accesses the App Store for in-app purchases or if you need to download an app from the App Store (as the App Store cannot be accessed through an HTTP proxy due to certificate pinning restrictions).

To intercept requests fired only by Tune SDK:

  1. Once mitmproxy starts, press capital i to see the list of host regex patterns.

  2. Press a to add a new pattern and paste the following:

    ^((?!mobileapptr|tuneapi|measurementapi).)*$
    
  3. Save the pattern by pressing Tab (right arrow key twice, then Tab).

  4. Press q to go back one screen.

Configure Your Mobile Device To Use mitmproxy Running On Your Mac

  1. Make sure mitmproxy is running on your Mac.
  2. On your mobile device, open the network settings Wi-Fi section.
  3. Connect to the same network your Mac is on.
  4. Set the Wi-Fi network to use an HTTP proxy with the following settings:
    • Select "Manual" option.
    • Set the value of Server to the IP address of your Mac (192.168.1.76 in the above example).
    • Set the value of Port to the port value that shows up in the mitmproxy window (8080 by default).
    • Leave authentication, username, and password empty.
  5. Tune SDKs use HTTPS requests. To allow the proxy to handle the HTTPS traffic, a certificate needs to be installed on your mobile device. To install the certificate:
    • Open http://mitm.it in the mobile web browser. This should open a webpage that will allow you to download the mitmproxy certificate.
    • Tap the icon for your mobile platform: iOS, Android, etc.
    • When the downloaded file opens automatically, tap Install to install the proxy certificate.

Now you can view the network traffic from your mobile device through mitmproxy.

🚧

Security Note

Some apps – like Apple App Store app – may not be able to access the internet when using mitmproxy.

Verify Expected Network Results

  1. Run your app and check the mitmproxy window to make sure that the expected network requests are being fired for each Tune measure call.
  2. A network request list appears
  3. When you are finished using mitmproxy:
    • Disable the HTTP proxy on your mobile device.
    • Quit mitmproxy on your Mac.

Reading Server Responses

You can receive and read the server responses from the TUNE SDK calls to help diagnose and debug your SDK implementation. These responses can provide helpful error messages and success notifications.

Android SDK Server Response Debugging

The following sample code shows a class that implements the TuneListener interface and outputs the server response(s) to LogCat. Override the methods with your own to make use of the server responses.

public class MyTuneListener implements TuneListener {
    @Override
    public void enqueuedActionWithRefId(String refId) {
        Log.d("TUNE", "enqueuedActionWithRefId " + refId);
    }

    @Override
    public void enqueuedRequest(String url, JSONObject postData) {
        Log.d("TUNE", "enqueuedRequest " + url + " " + postData);
    }

    @Override
    public void didSucceedWithData(JSONObject data) {
        Log.d("TUNE", "didSucceedWithData " + data);
    }

    @Override
    public void didFailWithError(JSONObject error) {
        Log.d("TUNE", "didFailWithError " + error);
    }

Create a new instance of this class and register it using the setListener method:

MyTuneListener listener = new MyTuneListener();
Tune.getInstance().setListener(listener);

Now when a TUNE request completes, the code in your custom TuneListener methods is run – outputting to LogCat in this example.

iOS SDK Server Response Debugging

The following sample code shows how to use the Tune debug handler. Route the debug log message to any log system.

Swift
Tune.setDebugLogCallback { (message:String) in
            // prints to the debugger log
            print(message)


            // prints to the debugger log and device log, does not redact anything
            //NSLog("%@", message)


            // prints to the debugger log and device log, redacts Strings by default
            // iOS 10+
            //os_log("%@", message!)
        }

        // Enables verbose debug messages, this very detailed and may include PII
        Tune.setDebugLogVerbose(true)
Objective-C
 [Tune setDebugLogCallback:^(NSString * _Nonnull logMessage) {
        NSLog(@"%@", logMessage);
    }];
    [Tune setDebugLogVerbose:YES];

Javascript SDK Server Response Debugging

The measurement functions in the Javascript SDK accept callback functions in their arguments.

function myCallback(data) {
    console.log("MAT server response: " + JSON.stringify(data));
};

// as a key in the request options:
MobileAppTracker.measureAction({eventName: "purchase",
                                callback: myCallback});
// as a second argument to the function:
MobileAppTracker.measureAction({eventName: "purchase"}, myCallback);

Now when a MAT request completes, the code in your custom callback functions is run – outputting to the console in this example.

Windows SDK Server Response Debugging

The following sample code shows a class that implements the MATResponse interface and outputs the response(s) to the console. Override the methods with your own to make use of the server responses.

public class MyMATResponse : MATResponse
{
    public void EnqueuedActionWithRefId(string refId)
    {
        // call has been queued, will be sent later
    }

    public void DidSucceedWithData(string response)
    {
        Debug.WriteLine("MAT.success: " + response);
    }

    public void DidFailWithError(string error)
    {
        Debug.WriteLine("MAT.failure " + error);
    }
}

Create a new instance of this class and register it using the SetMATResponse method:

MyMATResponse response = new MyMATResponse();
mobileAppTracker.SetMATResponse(response);

Now when a MAT request completes, the code in your custom MATResponse methods is run – outputting to the debug logs in this example.

Adobe Air Plugin Server Response Debugging

This setting causes MAT to log the server responses to the console:

MobileAppTracker.instance.setDelegate(true);

PhoneGap Plugin Server Response Debugging

This setting causes MAT to log the server responses to the console:

window.plugins.tunePlugin.setDelegate(true, successCallback, errorCallback);

Unity Plugin Server Response Debugging

The following sample code shows a Unity script that implements the MobileAppTrackerDelegate callback methods and logs the responses to the console. Override the methods with your own to make use of the server responses.

using UnityEngine;
using System;
using System.Collections;
using System.Collections.Generic;
using System.Runtime.InteropServices;

public class TuneListener : MonoBehaviour
{
    public void trackerDidSucceed (string data)
    {
        #if UNITY_IOS
        print ("TuneListener trackerDidSucceed: " + DecodeFrom64 (data));
        #endif
        #if (UNITY_ANDROID || UNITY_WP8 || UNITY_METRO)
        print ("TuneListener trackerDidSucceed: " + data);
        #endif
    }

    public void trackerDidFail (string error)
    {
        print ("TuneListener trackerDidFail: " + error);
    }

    public void trackerDidEnqueueUrl (string url)
    {
        print ("TuneListener trackerDidEnqueueUrl: " + url);
    }

    /// <summary>
    /// The method to decode base64 strings.
    /// </summary>
    /// <param name="encodedData">A base64 encoded string.</param>
    /// <returns>A decoded string.</returns>
    public static string DecodeFrom64 (string encodedString)
    {
        print ("TuneListener.DecodeFrom64(string)");
        return System.Text.Encoding.UTF8.GetString (System.Convert.FromBase64String (encodedString));
    }
}

Call the setter to enable the delegate functionality.

Tune.setDelegate(true);

The TUNE plugin uses the name "TuneListener" when sending delegate callbacks. Make sure you create a GameObject by the name "TuneListener" in your Unity project, and attach the above script (that implements the TUNE delegate callback methods) to that GameObject. To do this automatically, you can also select TUNE → Setup → Delegate Callbacks → Create TuneListener Object in the Unity menu.

Xamarin Plugin Server Response Debugging

The following sample code shows a class that implements the MobileAppTrackerDelegate interface and logs the responses to the console. Override the methods with your own to make use of the server responses.

public class TestMATDelegate : MobileAppTrackerDelegate
{
    public override void MobileAppTrackerDidSucceed (NSData data)
    {
        Console.WriteLine ("MAT DidSucceed: " + NSString.FromData(data, NSStringEncoding.UTF8));
    }

    public override void MobileAppTrackerDidFail (NSError error)
    {
        Console.WriteLine ("MAT DidFail: error = " + error.Code + ", " + error.LocalizedDescription);
    }

    public override void MobileAppTrackerEnqueuedAction (string referenceId)
    {
        Console.WriteLine ("MAT EnqueuedAction: advertiserRefId = " + referenceId);
    }
}

Create a new instance of this subclass of MobileAppTrackerDelegate and register it using the SetDelegate setter method:

TestMATDelegate matDelegate = new TestMATDelegate();
MobileAppTracker.SetDelegate(matDelegate);

Now when a MAT request completes, the code in your custom TestMATDelegate methods is run – outputting to the console in this example.

Spike of Total Installs on the First Day

If your total installs spike on the first day of launching the SDK in your mobile app (when you publish your mobile app Live in the Apple App Store, Google Play Store, or Amazon Appstore for Android) and then suddenly drop again, then it’s likely that the code to differentiate app "installs" versus "updates" is not properly implemented within the SDK.

For information about how to properly handle existing users, please visit Handling Existing Users prior to SDK implementation.

Specifically, the local preference (that you set months or years ago) was not present until you implemented the SDK, which already handles differentiating "installs" verses "updates" after you implement the SDK and submit your mobile app to an app store. Use an old preference in the code so that the SDK can differentiate the installs that occurred prior to SDK implementation.

If you do not indicate to the SDK or MAT platform that a user already installed the app prior to SDK implementation, then MAT logs the update as an install (thereby potentially attributing the install to an advertising partner or publisher even though they’re already a user of your app), which can impact reporting accuracy and possibly require you to pay the partner for installs that you already acquired. This issue can also create discrepancies when you reconcile your reports with iTunes or Google Play.

Testing Your Mobile App

Since the SDK can log conversions generated through the Apple iTunes App Store, Google Play Store, Amazon Appstore for Android, and other third parties, you should test conversion measurement without actually updating your mobile app listing in the production environment. First confirm that the Tune SDK is successfully working before you update your mobile app in its respective app store. You can save an enormous amount of time, resources, and frustration by first testing that all functions are operational before updating your mobile app for the app store. For Android apps in the Google Play Store, make sure that your app is properly collecting the Install Referrer as described at Testing the Google Play Install Referrer.

📘

Note

Before you start testing, first make sure that you integrated the Tune SDK as described at iOS SDK or Android SDK. Then set up a test profile as described in Creating a Test Profile.

After you set up your test profile, generate a TUNE link:

  1. Log in to Attribution Analytics.
  2. In the navigation (on the left side), under the Applications section, expand Testing, and then click Test Mobile App.
  3. On the Test Mobile App page, from the drop-down lists for each field (such as Mobile App, Partner, Campaign Type, Destination URL), make the appropriate selections so Attribution Analytics can automatically generate the appropriate TUNE link for your app.
  4. To append the device identifier (that you specified in your test profile) and/or other optional parameters, scroll down to the Parameters section, open the Identifiers for App-to-App Attributionaccordion menu and add the device identifier. As you type specific parameters to include, the TUNE link updates with those values.
  5. To send yourself an email with the updated TUNE link (which now includes your optional parameters), below the TUNE Link box, click the "envelope" icon.
  6. In the new email window (that already includes the updated TUNE link in the body of the email), attach your .APK or .IPA file (ad-hoc app build), and then click Send.

Before you can install a developer app on an Apple device, first set up a provisioning file as described in Provision an iOS Device. If you use TestFlight, see Testing iOS SDK integration with TestFlight.

Include Test Data in Reporting

After you set up a test profile in Attribution Analytics and run a test (for example, perform a mobile app install on your test device), you must include test data in your reports (else you will not see the test install event because by default Attribution Analytics excludes test data from reporting). To include test data in your reports:

  1. In the navigation, under the Reporting section, click the desired type of report (for example, Actuals, Cohort, Retention, or Logs).
  2. On the report page, next to the date time in the upper-left corner, click Edit.
  3. In the parameters and filters panel, scroll down to the Filter section at the bottom, remove the Test Data: Exclude filter, and then click Apply.

Testing SDK Implementation

You can use this testing process and functionality to test the Attribution Analytics SDK and ensure that it's implemented appropriately (is logging clicks, installs, and other in-app events accurately). For additional implementation testing and troubleshooting information, see Android SDK Implementation Troubleshooting and/or iOS SDK Implementation Troubleshooting.

Testing the Google Play Install Referrer

🚧

Note

The following methods for testing the proper collection and passing of the Google Play Install Referrer are only applicable for apps running the TUNE SDK versions 4.14.0 and below.

After you integrate the TUNE SDK into your Android app (but before you submit your app to the Google Play Store), make sure that the Google Play Install Referrer is being collected and passed properly to avoid any missed attributions and/or attribution discrepancies.

Common Signs of an Issue Collecting the Install Referrer

When the Google Play Install Referrer is not setup properly in your app code, then you may see one or more of the following effects when testing your mobile app:

  • Installs are attributed as Organic instead of being credited to the appropriate advertising partner (whomever is referenced by the Install Referrer/TUNE tracking ID)
  • Integrations with Google Analytics may show relevant activity (such as page visits and ad clicks), but installs are not recorded properly
  • Integrations with Google Analytics may show installs, but they are not attributed to the proper source

Possible Causes and Solutions

Some possible causes for why an Install Referrer is not captured or passed properly include:

  • No test profile enabled in Attribution Analytics. Without a test profile enabled for your device and app, TUNE rejects duplicate installs and you may not see events in Attribution Analytics. For information about configuring a test profile, please visit Creating a Test Profile.
  • Multiple BroadcastReceivers for the same event. If you have more than one BroadcastReceiver listening for the same event or action, then it becomes uncertain which one will handle the intent and which one(s) will not. To support multiple BroadcastReceivers, you can create one receiver that passes the intent to other receivers (which are essentially subclasses of the one receiver) as described at Multiple Android Install Referrers.
  • For integrations with Google Analytics, the BroadcastReceiver used is not the one required for a specific version of Google Analytics. Make sure you are referencing the appropriate receiver.
    • For Google Analytics v2:
      com.your.package/com.google.analytics.tracking.android.CampaignTrackingReceiver
    • For Google Analytics v3:
      com.your.package/com.google.android.apps.analytics.AnalyticsReceiver
    • For Google Analytics v4:
      com.your.package/com.google.android.gms.analytics.CampaignTrackingReceiver

Testing the Install Referrer with the TUNE Referrer Test App

The TUNE Referrer Test app allows you to easily test if your Install Referrer Receiver is setup correctly.

Once you have launched your app, log into Attribution Analytics and go to the Test Logs.

  1. Click the Configure Report button.
  2. Search for and select the Referral URL metric.
  3. Click the Filters tab.
  4. Type in Referral Test Successful and click Add.
  5. Click Apply.

Testing the Install Referrer with ADB

First, enable TUNE debugging:

// Do not enable this for release
Tune.setDebugMode(true);

To make sure that the install referrer is working properly, run the following command in an Android Debug Bridge (ADB) terminal:

adb logcat -s "TUNE"

This will start LogCat monitoring for the "TUNE" tag.

In a separate terminal, run:

adb shell
am broadcast -a com.android.vending.INSTALL_REFERRER -n {com.your.package}/com.tune.TuneTracker --es referrer "test_referrer=test"

📘

Note

The -n parameter (which specifies the receiver) is optional. Omitting this parameter is a good test to see if the receiver is found by the broadcast (or if using multiple receivers, which particular receiver gets the broadcast).

When the install referrer is working properly, you should see output similar to the following in your LogCat output:

09-19 11:56:23.123: D/TUNE: TUNE received referrer test_referrer=test

For more information about testing your TUNE SDK integration, see:

Testing the iOS SDK Integration with TestFlight

To test your integration of the TUNE SDK for iOS, you can use TestFlight. After you upload your test build (of your mobile app) to TestFlight, invite testers to test your app by providing them with a test TUNE link (tracking link). After opening the test TUNE link on their mobile device, testers need to install the test build.

Creating a Test Profile

Before you begin testing with TestFlight, you'll need to create a test profile which enables you to repeatedly test using the same device based on the whatever unique device identifier you provide. Without a test profile, our measurement engine will block duplicate installs from the same device and therefore testing can't proceed.

📘

Note

If you are testing using an iOS device, you'll need to set up your test profile using your IP Address as the device identifier. Do not use your iOS device's IFA, as TestFlight randomizes the IFA of the device during testing which would block TUNE from recognizing your single test device.

Registering the Testing Device

All testers need to have TestFlight installed on their iOS device and their device registered. After they successfully complete registration, you can invite them to test the builds of your apps.

When you invite testers to test a build, TestFlight sends them an email notification with a link to download the build.

Testing Instructions

The easiest way to test TUNE with TestFlight is for the tester to send an email that includes a test TUNE link in the body of the email. Clicking this URL from a test device starts a logging session and then the tester proceeds to install the app using TestFlight.

To generate a TUNE link in your Attribution Analytics account, view the app, then click Create TUNE Link. The following URL shows a sample TUNE link:

https://1.api-01.com/serve?action=click&publisher_id=6136&site_id=1863&campaign_id=234595

Compose an email to yourself (or to the person testing the iOS mobile app), include the test TUNE link in the email, and then send the email.

From the iOS test device, open the email and click the TUNE link to start a logging session. While the TUNE link may redirect users to the production version of the mobile app (on the App Store), TUNE still logs the conversion properly, so long as the TUNE link is opened from the same iOS test device.

After a logging session starts on the iOS test device, open the email from TestFlight (that includes the URL to download the build to test), and then install the test build of the app.

Test the installation of the app by opening it. Proceed to the point where the measureSession and/or measureAction methods are called, which is when TUNE records the conversion and associates it with the click event. Log in to TUNE and check the Install and/or Event Reports to see if TUNE logged the install and/or event properly.

When this testing process proves successful (click and install events for your mobile app are being logged properly in your Branch account), you are ready to update the production version of your mobile app in the App Store.


Did this page help you?