Android
Installation Instructions for TagCommander on Android.
TagCommander offers dedicated Plug-Ins for all major native App platforms. Please refer to the SDK documentation on GitHub for detailed installation instructions for Android.
Introduction to mobile app tagging
TagCommander’s SDK allows you to trigger tags from a mobile application.
Commanders Act offers a so-called “super light” SDK you can include in your mobile app’s code; its purpose is to reduce calls to partner solutions as much as possible in order to improve your app’s performance and user experience. A unique call is issued to TagCommander’s servers the moment the app’s screen is displayed or than an element on the screen is clicked. Information related to the page browsed or the element that is clicked is then sent separately to partner solutions by TagCommander’s servers; this allows to prevent applications’ loading speed from slowing down.
Note: Not all solutions are compatible with this method. Since the light SDK sends app information to partner solutions’ servers, they cannot “go back” to the app. Adserving solutions (those displaying adverts) and push notification providers are thus not compatible with this method.
The basic operational principle of TagCommander’s light SDK is:
– Step 1: the mobile data layer and TagCommander’s SDK are called in the app’s source code every time the screen loads or that an element is clicked. (your IT staff should have implemented this at the start of the project).
– Step 2: TagCommander’s SDK issues calls to TagCommander’s servers and automatically sends the mobile data layer’s contents. This is the server-side hits’ structure:
https://serverside$siteID$.tagcommander.com/$containerID$/
$siteID$ and $containerID$ : TagCommander site and container ID. Variables in the mobile data layer are sent to TagCommander’s servers wit a POST method (i.e. in the https request’s head).
– Step 3: TagCommander’s servers send the received information to the different partner solutions. There are as many outgoing hits as there are partner solutions you wish to send information to.
Ex: if you wish to issue a call to both Criteo and Google, a hit will be sent to either solution’s servers.
Implementing TagCommander on a mobile application is a project that consists of the steps listed hereunder:
Definition of the mobile application’s tagging plan: selection and definition of internal and external variables.
Creation of a mobile container and configuration of tags within the TagCommander interface.
TagCommander SDK implementation in the app’s source code.
Acceptance testing of the implementation in a test environment.
Publishing (+ container updates)
Step #1: defining the application's tagging plan
The tagging plan corresponds to the list of variables that will populate the app. There are two types:
External variables, present within the app’s source code and programmed by technical staff.
Internal variables calculated within TagCommander’s SDK (mobile variables), or on TagCommander’s servers (server-side variables).
Both external and internal variables need to be declared in the interface beforehand (this is usually done by a Commanders Act consultant).
Mobile Data Layer: external variables
Mobile external variables are declared by your IT staff in the application’s source code and sent automatically to the servers by TagCommander’s SDK.
You can use these external variables to populate mobile tags or to create rules to execute them.
To learn more about external variables and steps to declare them in the interface please click here.
Mobile Data Layer: internal variables
Mobile internal variables are automatically calculated by TagCommander’s SDK or servers. You can use these variables to populate mobile tags or to create rules to execute them.
Mobile internal variables are reunited in the interface options’ “Server-side” > “Internal Variables” tab.
You will find, among the predefined internal variables, some that are calculated by TagCommander’s servers (“Server-side”) and designed for iOS (“iOS”), Android (“Android”) or both (“Mobile (iOS + Android)”). Click the blue “Add predefined variables” button (1) to access them and select a predefined universe (2):
Mobile (iOS + Android): internal variables that are automatically calculated by the SDK and designed for both systems.
TC_IP: the device’s IP address; it is only available if it is connected to the internet. (ex: “10.144.112.50”)
TC_LANGUAGE: the device’s language and location (ex: “fr_FR”)
TC_SYSNAME: the device’s operational system’s full name (ex: “Android-4.2.2” / “iPhone OS”)
TC_SYSVERSION: the device’s operational system’s version (ex : “4.2.2” / “8.4.1” for an iPhone 4s)
TC_MODEL: the device’s model (ex: “Nexus 7” for a Nexus 7; “A0001” for a OnePlus One, “GT-I9305” for a Galaxy S3, “iPhone” for an iPhone 4s)
TC_CONNEXION: connection type (ex : WIFI)
TC_DEVICE: name given to the device by the device’s owner (ex: “flo”)
TC_SCREEN: the device’s screen resolution (ex: “1920×1104” for a Galaxy Tab 3, “320×480” for an iPhone 4s)
TC_CHARSET: the device’s default character encoding method (“UTF-8” for a OnePlus One, “MacRoman” for an iPhone 5)
TC_CURRENCY_CODE: the device’s default currency code (ex: “EUR”, “CAD”)
TC_CURRENCY_SYMBOL: the device’s default currency symbol (ex: “&dollar”, “&euro”)
TC_APPLICATION_VERSION: the device’s application version allowing to run Commanders Act’s SDK (ex : “42.2.12”)
TC_APPLICATION_PREVIOUS_VERSION: The application’s previous version’s number whenever available (ex: “42.2.10”, blank otherwise)
TC_APPLICATION_BUILD: the application’s build number (ex: iPhone 5: 2.3 / Nexus 7: 1536)
TC_TAGCOMMANDER_VERSION: TagCommander’s SDK version in the following format: “version.release-date”
TC_MANUFACTURER: name of the device’s manufacturer (ex: “Apple”, “Samsung”)
TC_USER_AGENT: the device’s web browser’s user agent
TC_JAILBROKEN: jailbroken device (= “1”) or factory settings (= “0”)
TC_APPLICATION_STARTS: Number of the application’s cold starts. Cold starts correspond to the app’s first launch after a system reboot or whenever the app is closed and relaunched
TC_FOREGROUNDS: number of times the app is running in the foreground
TC_FOREGROUND_TIME: amount of time during which the app is open in the foreground (milliseconds)
TC_DELTA_FOREGROUND_TIME: time frame between the current time and date and the last time the app was opened in the foreground (milliseconds)
TC_BACKGROUND_TIME: amount of time during which the app runs in the background (milliseconds)
TC_DELTA_BACKGROUND_TIME: time frame between the current time and date ad the last time the app was running in the background (milliseconds)
TC_BACKGROUND_UX_TIME: amount of time during which the application runs in the background while interactive content is served to the user (milliseconds)
TC_DELTA_BACKGROUND_UX_TIME: time frame between the current hour and the last time the app ran in the background while interactive content was being served to the user (milliseconds)
TC_CURRENT_CALL_MS: time stamp of the hit’s generation (milliseconds)
TC_LAST_CALL_MS: time stamp of the previous hit’s generation (milliseconds)
TC_LAST_SESSION_LAST_HIT_MS: time stamp of the last hit registered during the last session (milliseconds)
TC_NOW_MS: Unix Time stamp (milliseconds)
TC_IDFA: Id of Google or Apple-served ads
TC_IS_TRACKING_ENABLED: indicates whether tracking is accepted on the device (YES/NO)
TC_LIMIT_USER_TRACKING_ENABLED: limited tracking on the device (YES/NO)
TC_LONGITUDE : user’s longitude if geolocation is authorized
TC_LATITUDE: user’s latitude if geolocation is authorized
TC_BUNDLE_IDENTIFIER: Id of the app’s batch allowing Commanders Act’s SDK to run
TC_APPLICATION_NAME: Name of the app allowing Commanders Act’s SDK to run
TC_RUNTIME_NAME: Device type (ex: Android / iOS)
TC_FIRST_VISIT_MS: time stamp of the app’s first launch (milliseconds)
TC_LAST_VISIT_MS: time stamp of the last visit’s start (milliseconds)
TC_CURRENT_SESSION_MS: time stamp of the current session (milliseconds)
TC_CURRENT_VISIT_MS: time stamp of the current visit (milliseconds)
TC_SESSION_DURATION_MS: current session’s length (milliseconds)
TC_VERSION_FIRST_VISIT_MS: for the app’s current version, it is the first time stamp of the first session following an app update (milliseconds)
TC_NUMBER_VISIT: number of times a user opened the app
TC_NUMBER_SESSION: number of sessions created in the app
TC_IS_FIRST_VISIT: whether it is the first time the app is launched (= “TRUE”) or not (= “FALSE”)
TC_FIRST_EXECUTE: the first time a developer executes the app with the execute() or SendData() functions after the latter is launched (= “TRUE” or “FALSE”). This variable can be combined with the TC_IS_FIRST_VISIT variable to retrieve the very first hit sent the first time the app was launched.
***
Android: internal variables calculated automatically by the SDK and specific to Android.
TC_UNIQUEID: random 64-bit number generated when the user sets-up the device for the first time. It remains the same throughout the device’s lifetime.
Step #2: creating a mobile container and configuring tags in the TagCommander interface
Creating a container for mobile applications
TagCommander’s SDK issues calls to TagCommander’s servers: you therefore have to create a “server-side” technology-based container for your mobile applications.
Please note: you can use a single server-side container for both the iOS and Android versions of your apps.
To learn more about how to create a server-side container, see serverside user manual.
Implementing tags on mobile apps
Implementing mobile tags is the same as implementing server-side tags (see serverside user manual)
Step #3: implementing the SDK in the applications' source code
The SDK implementation is performed by technical staff or IT departments.
These elements must be provided:
The app’s TagCommander tagging plan, which lets IT staff know which variables to declare and on which screens or elements.
Technical documentation referring to each and every app. It must contain elements that are key to setting up the SDK and screenshots of setup examples.
Click here to read the corresponding technical documentation for Android: https://github.com/TagCommander/Android/blob/master/TCSDK/README.md
The site’s ID (Commanders Act account number) and that of the server-side container, which are necessary to set-up the SDK. These two elements can be retrieved in the container’s options section: click the “container options” icon (1) and copy the site (2) or container ID (3)
Step #4: Testing the setup in a test environment
TagCommander’s SDK can be tested with many different tools:
Tests for Android with Android Studio
TagCommander’s SDK for iOS can be tested with developing software “Android Studio”: https://developer.android.com/studio/index.html
In order to test your app, connect your Android phone to your PC.
Open the “Android Studio” app > Click “Start a new Android Studio project”. Click “Next” while on the following screens until you reach the main one called “Android Monitor”.
Then select your Android device (1) and choose the app you wish to test from the list (2).
To speed up tests, type “TagCommander” into the search engine (3).
These elements will be displayed when you analyze mobile logs (4):
TagCommander SDK’s version number: “Commanders Act SDK init with version: VERSION_NUMBER”
TagCommander’s site and container number: “SDK init with siteID SITE_ID and CONTAINER_ID
A list of the external variables that were provided by technical staff and that are visible in Android Studio, thanks to this function “TCLogLevel_Debug”: “Tag Commander Executing with appVars : AppVars : {#VARIABLE#: VALUE}”
Server-side hit containing variables sent to TagCommander servers (POST method). You will see internal variables first, followed by external variables): “sending: http://serversideSITE_ID.tagcommander.com/CONTAINER_ID/ With POST data: VARIABLE=VALUE&VARIABLE=VALUE…”
***
Running tests for Android or iOS with Charles Debugger
TagCommander’s SDK for both iOS and Android operating systems can be tested with the “Charles Debugger” proxy, downloadable for free here: https://www.charlesproxy.com/
The first thing to do is to configure your phone so it can communicate with Charles.
In your phone’s settings, go to the Wi-fi configuration tab.
Select your network and proceed to the advanced options to edit Wi-fi settings.
Add a proxy manually:
Proxy’s name (server)(1): Computer’s IP (you can find it in the “Local IP address” tab from Charles’ options)
Port (2): 8888
Save.
Go to the Charles app and authorize it to connect to the phone.
Browse the web with your phone and in Charles (on your computer) apply a “TagCommander” filter to see server-side hits displayed in the “Overview” section. They look like this: http://serversideSITE_ID.tagcommander.com/CONTAINER_ID/
When you go to the “Request” area, you will be able to see all variables and the corresponding values that are sent through the TagCommander SDK.
HTTPS Protocol:
Most of the time, server-side calls are issued through an https protocol.
Seeing https hits with Charles requires a more complex configuration. You will need to open your phone’s browser while Charles runs on your computer and go to this URL on your phone http://www.charlesproxy.com/getssl/
Download the certificate and install it; you will need to enter its name for two applications “VPN and applications” and “Wi-fi”.
Go back to Charles > “SSL proxy settings” > “SSL Proxying” > check “Enable SSL Proxying” > Click “Add” and type “*” in the “Host” field (to authorize any given host).
Then proceed to running tests the same way you do for http hits.
Step #5: publishing and updating containers
When the implementation is ok on your testing environment, you need to submit your app to app stores (Apple Store or Android Market) and wait for them to approve changes and include the new version in their catalogues.
This is a one-time procedure you will not need to repeat. This is because TagCommander’s SDK is available on JCenter for Android and Cocoapods for iOS, allowing developers to include a link leading to the latest version of TagCommander’s SDK in the applications.
To learn more about JCenter and Cocoapod, please refer to this content:
JCenter for Android : https://github.com/TagCommander/Android
Cocoapods for iOS : https://github.com/TagCommander/pods
Last updated