Troubleshooting

Basics

When testing mobile apps, we recommend that you only test in the Tealium dev environment, and not in prod. Also, use a build of the app specifically designed for testing. If you must use a production build for testing, such as when you test an app’s appearance in the App Store or Play Store, see the Charles Proxy section below on switching environments to avoid making changes to the live application.

When publishing changes while debugging, you are subject to the five minute expiry time in Tealium’s cache. During this time, the utag.js files are refreshed on Tealium’s servers after you publish.

Each time you launch the app from a cold start (app was previously swiped away from the app tray), the Tealium SDK checks for new files, and subsequently every 15 minutes by default (controlled by mobile publish settings. However, if less than five minutes have passed since publishing, restarting the app does not always work until after the five minute expiry time. Switching between the dev and qa environments while testing may alleviate this problem, because the cache on the environment expires if not used within the last five minutes, and the new file becomes available immediately.

Tealium EventStream Live Events

The Live Events feature in Tealium EventStream is available to all Tealium customers for the purpose of debugging mobile installations.

If you use this troubleshooting method in a production environment, you may be charged for the volume usage. Be sure to disable this feature before your app goes live.

Use one of the following methods to enable the event collection feature.

Option 1 - Tealium Collect Tag

Add the Tealium Collect tag from the tag marketplace. In the Advanced Settings of the tag, toggle off the QA and Prod environments to avoid publishing the tag to production and incurring usage charges. Requests are sent out from the app as encoded JSON data in a POST request, so this method is more difficult to use in conjunction with Charles Proxy, but the advantage is that you are able to see all data from the webview, including cookie data and variables modified by extensions. If you do not enter a specific profile in the tag configuration, data is sent to the same profile the app is targeting. If you want to send data to a specific profile, see the Tealium collect tag setup guide.

Option 2 - Tealium Collect Module

In your Tealium iQ account, go to the Mobile Publish Settings and enable Tealium Collect. The advantage to this method is that data is transmitted as a GET request, and each data variable is added to the query string in the form of easily-readable query parameters. This method is best if you intend to use Charles Proxy to inspect the data. Be sure to turn this setting off before pushing app to production to avoid unexpected usage charges. Only the exact data that was passed to Tealium by the app developers is seen, and not the data from the webview in this request such as cookie data or extension-generated data.

By default, data sent using this feature is sent to the “main” profile in your account and not the currently selected profile in your app. To adjust this behavior, override the dispatch URL using the following code snippets in your app, and substitute the appropriate account and profile combination:

Tealium.Config config = Tealium.Config.create(application, "[ACCOUNT]", "[PROFILE]", "ENVIRONMENT");config.setOverrideCollectDispatchUrl("https://collect.tealiumiq.com/vdata/i.gif?tealium_account=[ACCOUNT]&tealium_profile=[PROFILE]");

TEALConfiguration *configuration = [TEALConfiguration configurationWithAccount:@"[account]"profile:@"[profile]" environment:@"dev"];[configuration setOverrideCollectDispatchURL:@"https://collect.tealiumiq.com/vdata/i.gif?tealium_account=[account]&tealium_profile=[profile]"];

After you have configured one of the collection methods above, log in to EventStream and go to Live Events to see the incoming events.

For more information, see Live Events.

Charles Proxy

The Charles web debugging proxy inspects all HTTP and SSL/HTTPS traffic between your device and a third-party service that you have configured through Tealium iQ Tag Management.

Set up Charles to proxy your Android or iOS device.

Switching Tealium Environments

You may need to switch from the default environment the app is targeting (for example, prod) to a different environment to view your changes. To switch environments, add a custom mapping in Charles Proxy (or other proxy tool such as Fiddler), which transparently switch out the files that are being served to the app. For example, the app requests the prod utag.js file (https://tags.tiqcdn.com/utag/tealiummobile/demo/prod/utag.js), but Charles proxy serves back the dev utag.js (https://tags.tiqcdn.com/utag/tealiummobile/demo/dev/utag.js)

The following configuration steps switch to a different Tealium environment:

1. Open Charles Proxy and go to Tools > Map Remote. In the Map Remote Settings screen, check Enable Map Remote and then click Add.
2. In the Host box, paste https://tags.tiqcdn.com/utag/<account>/<profile>/prod/*, substituting your account and profile into the URL. After pasting, move your cursor and click in the Port or Path field of the Map From section, and Charles automatically separates the URL into its component parts.
3. In the Map To section, perform the same process again, this time changing the environment from prod to dev (or qa) in the URL, depending on which environment you want to target. Remove the asterisks character from the end of the URL, for example: https://tags.tiqcdn.com/utag/<account>/<profile>/dev/
4. Click OK to complete the setup.

Charles Proxy now switches all requests from the prod environment to the dev environment. To switch back to the app’s default environment, disable or delete the Map Remote rule, or turn off the proxy on your device.

Exit the app and relaunch it for this setting to take effect.

Traffic Inspection

The following table lists common examples of requests to inspect using Charles proxy:

Trace

For more information, see trace.

Analytics Tools

To set up Google Analytics to troubleshoot your configuration, use the following steps:

1. Set up a test Google Analytics account for yourself, and note the property ID (for example, UA-12345678-1).
2. Add the Google Analytics tag through Tealium IQ, entering your new property ID in the relevant configuration field.
3. Enable screen views in the GA tag, and map one of your data variables to screenName.
4. (Optional) Set up a custom event in GA by mapping any two variables to Event Action and Event Category respectively. If the app is functioning correctly, screen views and custom events appear in your Google Analytics account. A custom event is automatically generated so long as Event Category and Event Action are set, and it doesn’t matter which specific data you pass to these variables for test purposes.

Device Logs

Standard Device Logs

If you filter the console with tealium, you might see these logs more clearly.

Tealium Debug Logs

Debugging mobile.html

This section shows how to troubleshoot a mobile implementation of Tealium iQ Tag Management via the published file mobile.html.

When you activate a mobile profile in Tealium iQ, a file named mobile.html is published to the following path:

http://tags.tiqcdn.com/utag/{ACCOUNT}/{PROFILE}/{ENVIRONMENT}/mobile.html

The native module library uses this file to receive mobile publish settings and to facilitate the Tag Management module. This file is useful to perform some basic troubleshooting of your mobile implementation.

Inspecting mobile.html

The behavior of utag.js on the mobile.html page is similar to that of a standard desktop website page. The utag.js file is loaded and subsequent vendor tags are executed.

To inspect the mobile.html page:

1. In a new browser window, load the mobile.html URL for your iQ profile.
2. Open the developer tools or web console of the browser to inspect the page source.

From here, you can perform many of the same troubleshooting techniques that are used for a website with Tealium’s utag.js installed.

Verifying the Publish Timestamp

The first thing to verify is that your most recently published changes are being loaded in mobile.html. You can verify the changes by matching the timestamp from the HTML source to the timestamp from the iQ Versions screen.

To verify the publish timestamp:

1. At the top of the page source of mobile.html, look for the published timestamp on the first line. The timestamp in mobile.html has the following pattern: ut.4.0.YYYYMMDDHHMM. (Time is always in GMT)
2. In your iQ profile, go the Versions screen and find the most recently published version of the same environment. The timestamp of this publish matches the timestamp found inside mobile.html.

Inspecting Mobile Publish Settings JavaScript Object

The mobile.html page uses a JavaScript object named mps to store the values of the mobile publish settings. Inspect this object to verify your settings.

To inspect the mps object:

1. Enter mps into the web console.
2. The properties marked 4 and 5 correspond to versions 4.x and 5.x of your mobile library respectively.

Simulating Tracking Calls

The behavior of utag.js on this page is similar to that of a standard desktop website page. Watch the network activity to see which utag.\*.js files are loaded and trigger tracking calls from the browser console to verify that your tags are working as expected.

To simulate tracking calls in mobile.html:

1. From the browser console, enter utag.view({screen_title : "Test Page"}).
2. Go to the Network Activity screen to inspect the outgoing vendor tracking activity.

Remote Debugging

Advanced users are able to debug the hidden webview using Chrome or Safari remote web inspector.