Troubleshooting
Learn about the various methods for validating your mobile installation.
Basics
When testing mobile apps, it is recommended to 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 (App Store/Play Store), see the section below on switching environments to avoid making changes to the live application.
When publishing changes while debugging, you are subject to the 5 minute expiry time on 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 it has been less than 5 minutes since publishing, restarting the app does not always work until after the 5 minute expiry time. Switching between the "dev"
and "qa"
environments while testing alleviates this somewhat, because the cache on the environment expires if not used within the last 5 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 enable this 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 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 config, data is sent to the same profile the app is targeting. If you wish 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, override the dispatch URL using the following code snippets in your app, and substitute the appropriate account/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]"];
Once you have configured one of the collection methods above, log in to EventStream and go to Live Events to see the incoming events.
Learn more about using 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 (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.
- Open Charles Proxy, and navigate to Tools > Map Remote. In the Map Remote Settings screen, check Enable Map Remote and then click Add.
- 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 into the Port or Path field of the Map From section, and Charles automatically separates the URL into its component parts. - 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 wish to target. Remove the asterisks character from the end of the URL, for example:
https://tags.tiqcdn.com/utag/<account>/<profile>/dev/
- 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.
Kill the app and relaunch it for this setting to take effect.
Traffic Inspection
The following are common examples of requests to inspect using Charles proxy.
Request | Description |
---|---|
\*.tealiumiq.com |
These hits are sent if you’re using Tealium AudienceStream’s Live Events feature for debugging, as described in Option 1 above. |
mobile.html |
Initial hit retrieving settings from Tealium. |
google-analytics.com, collect.gif |
If using Google Analytics, hits are sent to collect.gif , and the query parameters is inspected. |
/b/ss |
This filter picks up all hits to Adobe Analytics, and Context Data and/or props/eVars is shown in the query string. |
tags.tiqcdn.com |
To see which of your Tealium tags have fired, look out for hits to this server. If you don’t have bundling enabled then you’ll see individual files for each tag, for example the tag with UID 123 is utag.123.js . Be aware that if the files are cached, they won’t necessarily show in your Charles Proxy session, even if they have fired, so this is not always the most accurate way of testing. |
Trace
Learn about using trace for troubleshooting.
Analytics Tools
Set up a test Google Analytics account for yourself, and note the property ID (for example, UA-12345678-1).
Add the Google Analytics tag through Tealium IQ, entering your new property ID in the relevant config field.
Enable screen views in the GA tag, and map one of your data variables to screenName
.
(Optional) Set up a custom event in GA by mapping any 2 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 Action are set, and it doesn’t matter which specific data you pass to these variables for test purposes.
Device Logs
Standard Device Logs
- Install Android Studio on your machine.
- Enable USB Debugging on your Android device.
- Launch Android Studio on your PC/Mac, and ensure the “Android Monitor” (v3.1 and below) or “Run” (v3.2 and higher) is displayed at the bottom of the screen. If neither of those options are “View > Tool Windows > Android Monitor/Run” to show one of them.
- Connect your Android device with a USB cable. The logs from your device in the console become available. This shows the output from all apps, including the Android system itself, and if you are testing a production build, it is likely that only critical errors/crashes are logged.
- If you have version Android Studio 3.2 or higher installed, there are a number of other tools with the ability to debug/validate/troubleshoot.
- Install XCode on your machine.
- Connect your iPhone/iPad with a lightning cable.
- Go to “Window > Devices and Simulators”, in the “Devices” tab, select your device in the list.
- To see the device console, click the up-triangle at the bottom left of the right hand panel. The console displays logs from all apps on the device. If the app is a production build, it is likely that only critical errors/crashes are logged.
If you filter the console with “tealium” you might see these logs more clearly.
Tealium Debug Logs
- Open Android Studio and plug in your device.
- Set the Tealium Debug Level to the most verbose setting (“dev”") by calling the
.setForceOverrideLogLevel()
method. (For example,.setForceOverrideLogLevel("dev");
) - Run your project and view the output in the Logcat console. The publish settings, configuration settings, and payload is displayed on the console.
If you filter Logcat with “Sent queued dispatch” you might see these logs more clearly.
- Open Xcode and plug in your device.
- Set the Tealium Debug Level to the most verbose setting (“dev”) by calling the
.setLogLevel()
method.- iOS:
[tealConfig setLogLevel: TEALLogLevelDev];
- Swift:
setLogLevel(logLevel: TealiumLogLevel)
- iOS:
- Run your project and view the output in the
lldb
console. The publish settings, configuration settings, and payload is displayed on the console.
If you filter your IDE console with “datasources payload” you might see these logs more clearly.
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
This file is used by the native mobile library 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:
- Load the
mobile.html
URL for your iQ profile in a new browser window. - Open the developer tools or web console of the browser to inspect the page source.
From here you are able to 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
. This is done by matching the timestamp from the HTML source to the timestamp from the iQ Versions screen.
To verify the publish timestamp:
- At the top of the page source of
mobile.html
, look for the published timestamp on the first line. The timestamp inmobile.html
has the following pattern:ut.4.0.YYYYMMDDHHMM
. (Time is always in GMT) - 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:
- Type “mps” into the web console and hit enter.
- 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
:
- From the browser console, type
utag.view({screen_title : "Test Page"})
and hit enter. - 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
Ensure the app is configured to allow remote debugging of the Tealium webview (Must be done by the app developer at build time).
Navigate to chrome://inspect/#devices on a Chrome Browser
Ensure your device is connected to your machine with a USB cable.
In the list of web pages, look for the one hosted on tags.tiqcdn.com
. This is the Tealium webview (mobile.html
), which is inspected in the same way as described above. Whenever the app triggers a view or link request, any breakpoints you have set in your JavaScript tag templates are hit, and the value of the data layer is inspected as if it were a desktop website.
Follow Apple’s Safari Developer Guide to enable the web inspector in Safari for Mac OSX and in the iPhone/iPad’s device settings.
When you are able see your device on the Develop menu, open tags.tiqcdn.com/utag/ACCOUNT/PROFILE/ENVIRONMENT/mobile.html
in the list of open web pages on the device, and then continue to follow the instructions in method 5 above.
This also works when using an iOS simulator to debug your app.
You cannot debug web views in apps installed through the App Store or Apple Configurator. Web views can only be debugged if the app has been installed via XCode and run either on an iOS simulator or a physical testing device.
This page was last updated: July 12, 2023