Android
Last update : 19/07/2022
Release version : 4.6.0
Commanders Act enables marketers to easily add, edit, update, and deactivate tags on web pages, videos and mobile applications with little-to-no support from IT departments.
Instead of implementing several SDK's in the application, Commanders Act for mobile provides clients with a single SDK which sends data to our server which then create and send hits to your partners.
Owing to remote configuration tools, it is also possible to modify the configuration without having to resubmit your application.
The purpose of this document is to explain how to add the SDK module into your application.
- Weight about 40 ko in your application.
- Fully threaded and asynchronous.
- Offline mode (the hits are stored in the phone to be replayed at the next launch.)
- Very low CPU and memory usage.
- Dynamic variable storage. If a value never changes, it's possible to set it only once.
- The state of the phone is easily accessed through the module (network connection type, name of the phone, geographical location.)
- Background mode, in the case you really need to send data while the application is in background.
A dynamic variable is a combination of a name and a value. It is used to give the module data such as the name of the current screen or the product ID in a cart.
Dynamic Variables are implemented inside the application. They are replaced on the server at the time of the execution by the value transmitted.
A dynamic variable is formatted like this: #SCREEN#.
The dynamic variables are case sensitive. They should always be in upper case. The dynamic variable both begins and ends with a
#. Don't forget them when setting your dynamic variables.
Dynamic Variables has two purposes:
- Define information for analytics purposes. For instance, you would put
restaurants_listin the#SCREEN#dynamic variable. - Test if conditions are met to fire a tag. For instance, if you set the
#EVENT#toclick, the tag with the condition#EVENT# EQUAL 'click'will be executed.
When you call the sendData method, a hit will be packaged and sent to Commanders Act's server.
You can divide the integration of TagCommander's SDK into the next few steps:
- Adding the TagCommander library to your Project.
- Implementing TagCommander by tagging your application.
- Verify that all tags are being sent.
You need to add some dependencies in your build.gradle file for the SDK to work properly. You will need a tiny bit of google play services which is location.
implementation 'com.google.android.gms:play-services-location:15.0.1'
implementation 'com.android.support:appcompat-v7:27.1.1'
The SDK module is compiled with the following dependencies :
implementation project(':core')
implementation 'com.android.support:appcompat-v7:27.1.1'
TagCommander requires the following permissions:
- android.permission.INTERNET
- android.permission.ACCESS_NETWORK_STATE
- android.permission.ACCESS_WIFI_STATE
If not already done, you should also add the dependecy to the GMS library:
<meta-data android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
Localisation is a special case, if you want to use localisation, you will need to initialise the TCLocation class after TagCommander.
As of Android's SDK 23, we are only using the LOCATION group of permissions. In the case you need the latitude or longitude of the user, you will first need to ask your user for the LOCATION permission with "AppCompatActivity.requestPermissions".
TCLocation.getInstance(context);
And you will also need to add the following permission:
- android.permission.ACCESS_FINE_LOCATION
- android.permission.ACCESS_COARSE_LOCATION
- Minimum Android version is 15.
- Build Target version is 27.
- Build Tools Version : 27.0.3.
It is recommended to initialize TagCommander in your onCreate(Bundle savedInstanceState) in your MainActivity so it will be operational as soon as possible.
TC_SITE_ID and TC_CONTAINER_ID are integers provided by Commanders Act.
You need to pass your application context while instantiating TagCommander. The context is usually simply your activity from which we will be sure to get the application context.
A single line of code is required to properly initialize an instance of TagCommander:
//!\\ Very important while integrating TagCommander TCDebug.setDebugLevel(Log.VERBOSE);
TagCommander TCInstance = new TagCommander(TC_SITE_ID, TC_CONTAINER_ID, this);
This class is not a Singleton. If you have only needs for one pair of
site IDandcontainer ID, you might want to use it as a Singleton anyway for a greater ease of use.
If you want to use localisation, you will need to initialise the TCLocation class after TagCommander.
TCLocation.getInstance(context);
We have set the default setInterval to 30 minutes to save battery. If you need another time precision, you can set TCLocation.GPSInterval to any value and it will be used instead of the default value.
For every element that needs tagging in your application, you need to call addData on your TagCommander instance and when you want to send all those information to the server, you will simply need to call sendData.
TCInstance.addData("#EVENT#", "click"); TCInstance.addData("#PAGE#", "order"); TCInstance.addData("#AMOUNT#", "10000"); // don't forget to put numbers as String
TCInstance.sendData();
For compatibility reasons, we can still use TCAppVars to pass those information to TagCommander.
TCAppVars appVars = new TCAppVars(); appVars.put("#EVENT#", "click"); appVars.put("#PAGE#", "order"); appVars.put("#AMOUNT#", "10000"); // don't forget to put numbers as String
TCInstance.execute(appVars);
Always handle values as String !
Let's say that the URL you are using in your server-side container uses the following url:
:::url
http://engage.commander1.com/dms?tc_s=3109&tc_type=dms&data_sysname=#TC_SYSNAME#
&data_sysversion=#TC_SYSVERSION#&page=#SCREEN_NAME#&event=#EVENT#
In order to be executed, the tag needs two values:
#EVENT##SCREEN_NAME#
With the code from the previous section, this tag could be fired from Commanders Act's server. The application sends two dynamic variables (#EVENT# and #SCREEN_NAME#) and the SDK adds all information available to it (like #TC_SYSVERSION# and #TC_SYSNAME# in this hit).
To manage the privacy of the user's data you can use our Trust product, another product or nothing at all.
By default, the SDK will try to see if you have added our Privacy module. If so, it will put itself into a waiting for consent mode. In this mode, it will record all hits but wait to consent information to either send everything or delete all waiting hits.
If you don't use our Privacy module, the SDK will be enabled by default.
If you want to change those dehaviours, we added a way to initialise the TagCommander module with an additional information about the behaviour. For now we have 3 behaviours:
- PB_DEFAULT_BEHAVIOUR which is the one described just before
- PB_ALWAYS_ENABLED which forces the SDK to always send information. This is used when you have tags that don't require consent.
- PB_DISABLED_BY_DEFAULT which forces the SDK to disabled. It won't record hits before consent is given and you won't have any up by default time when using tagging the app loading screens. (This might only happen when you're not using our Privacy module)
To initialise the SDK with another behaviour, please call the following function:
TC = new TagCommander(TC_SITE_ID, TC_CONTAINER_ID, context, ETCPrivacyBehaviour.PB_DISABLED_BY_DEFAULT);
You can set the behaviour of the SDK using ETCPrivacyBehaviour enum wich holds three values :
PB_DEFAULT_BEHAVIOUR : Use this value for normal SDK behaviour, the sdk will wait for consent to be given and only then react according to that.
PB_DISABLED_BY_DEFAULT : Use this value to if you want the sdk storing the hits untill a consent is given to fire them.
PB_ALWAYS_ENABLED : Use this to force sending hits without consent if your solution doesn't require that.
There are some tags that need to be passed a list of dictionaries, usually representing products. By passing complex information, we are able to create and send complex hits or many hits at the same time.
Tags that needs to be passed a list of dictionaries are easy to spot in the configuration. They have appended to the name of the dynamic variable the name of the key that is retrieved from the dictionary.
Most of the time the data are provided ready to use, but we provide a TCProduct class representing a product and its possible values.
public void SendViewCart() { TCInstance.addData("#REGIONAL_CODE#", "eu"); TCInstance.addData("#EVENT#", "viewCart"); TCInstance.addData("#PARTNER_ID#", "868");// adding products TCProduct product1 = new TCProduct(); product1.ID = "22561563"; product1.priceATI = "253.50"; product1.quantity = "1"; TCInstance.addProduct("#ORDER_PRODUCTS#", product1);
TCProduct product2 = new TCProduct(); product2.ID = "21669790"; product2.priceATI = "223.10"; product2.quantity = "2"; TCInstance.addProduct("#ORDER_PRODUCTS#", product2);
TCProduct product3 = new TCProduct(); product3.ID = "3886822"; product3.priceATI = "45.99"; product3.quantity = "3"; TCInstance.addProduct("#ORDER_PRODUCTS#", product3);
TCInstance.sendData(); }
The following properties can be used with the TCProduct class:
- ID
- name
- quantity
- category
- priceATI
- discountATI
- priceTF
- discountTF
- trademark
- URLPage
- URLPicture
- rating
- inStock
If you want to add more properties, please use the method on your TCProduct instance:
product.customProperties.put("Menu", "12");
product.customProperties.put("TakeOut", "0");
If you are updating from an old version of the SDK you can still use old functions with TCAppVars and a list of products.
If your release build uses ProGuard to strip and obfuscate your code, you will need to add some configuration for the modules to keep working.
Just add the following line in your proguard-rules.pro.
ruby -keep class com.tagcommander.lib.* { ; }
If you want the source channel of your application in Commanders Act, please point the INSTALL_REFERRER broadcast toward our receiver TCReferrerReceiver :
It's as simple as adding the following lines in the AndroidManifest.xml of your application and inside the "Application" tag.
<receiver
android:name="com.tagcommander.lib.TCReferrerReceiver"
android:exported="true">
<intent-filter>
<action android:name="com.android.vending.INSTALL_REFERRER" />
</intent-filter>
</receiver>
Once the broadcast is received, TagCommander will store the full string into the #TC_INSTALL_REFERRER# predefined variable.
Example:
utm_source=adMob&utm_medium=banner&utm_term=running+shoes&utm_content=theContent
&utm_campaign=couponReduc&anid=adMob
While the application is goind to background, the SDK sends all data that was already queued then stops. This is in order to preserve battery life and not use carrier data when not required.
But some applications need to be able to continue sending data because they have real background activities. For example listening to music.
For those cases, we added a way to bypass the way to SDK usually react to background. Please call:
TC.enableRunningInBackground();
One drawback is that we're not able to ascertain when the application will really be killed. In normal mode, we're saving all hits not sent when going in the background, which is not possible here anymore. To be sure to not loose any hits in background mode, we will save much more often the offline hits. This only applies if the SDK is offline, meaning that you don't have internet.
If you want to show a privacy message to your users allowing them to stop the tracking, you might want to use the following function to stop it if they refuse to be tracked.
TCInstance.disableSDK();
What this function does is stopping all systems in the SDK that update automatically or listen to notifications like background or internet reachability. This will also ignore all calls to the SDK by your application so that nothing is treated anymore and you don't have to protect those calls manually.
TCInstance.enableSDK();
In the case you need to re-enable it after disabling it the first time, you can use this function.
The TagCommander SDK also offers methods to help you with the Quality Assessment of the SDK implementation.
We recommend using Log.VERBOSE while developing your application:
/*
* Verbose is recommended during test as it prints information
* that helps figuring what is working and what's not.
*/
TCDebug.setDebugLevel(Log.VERBOSE);
- Verbosity
| Constant Name | Verbosity |
|---|---|
Log.VERBOSE |
Print everything. |
Log.DEBUG |
Most useful information for debugging |
Log.INFO |
Basic information about TagCommander's state |
Log.WARN |
Warnings only |
Log.ERRORS |
Errors only |
Log.ASSERT |
Assertions only (not used). |
- The internal architecture is working with internal notifications. You can ask the Logger to display all the internal notifications with TCDebug.setNotificationLog(true);.
If you don't call TCDebug.setDebugLevel, not log will be printed at all.
There are three ways to verify that the module executes the tags in your application:
- By reading the debug messages in the console.
- By going to your vendor's platform and check that the hits are displayed and that the data is correct. Please be aware that hits may not display immediately in the vendor account. This delay differs widely between vendors and may also vary for the type of hit under the same vendor.
- You can also use a network monitor like Wireshark or Charles to check directly what is being sent on the wire to your vendors.
Starting Android 7 (Nougat) you will have a bit more troubles while trying to profile your applications with tools like Charles. Google introduced changes to trusted certificates.
Basically what is needed in order to see https hits in Charles and alike is a bit more configuration than just adding SSL certificate to the phone. You will need to add in your manifest application:
android:networkSecurityConfig="@xml/network_security_config"
And create a file named network_security_config.xml under the res/xml folder which should contain:
<network-security-config>
<base-config>
<trust-anchors>
<certificates src="system" />
<certificates src="user" />
</trust-anchors>
</base-config>
</network-security-config>
With this, you should be set!
- Enable the debug logs if you have any doubt.
- Check if TagCommander is called when you think it is. You should see it in the console logs.
- Make sure you have the latest version.
- Check if you are not stripping part of the module with ProGuard.
- Don't forget the # at the beginning and the end of each dynamic variable.
- Always use the String type for the value of each dynamic variable.
- Always use upper case dynamic variables.
- The dynamic variables are case sensitive.
- If you don't set the correct value for one dynamic variable, an empty string will replace it.
The SDK module permits storing of variables that remain the same in the whole application, such as vendors ID, in a TagCommander instance, instead of passing them to the instance each time you want to send data.
These variables will have a lower priority to the one given by the addData method but will persist for the whole run of the application.
TCInstance.addPermanentData("#VENDOR_ID#", "UE-55668779-01");
They can also be removed if necessary.
TCInstance.removePermanentData("#VENDOR_ID#");
TagCommander collects a great deal of information to function with accuracy. You can ask for any variables computed by TagCommander through a simple getData on TCPredefinedVariables.
The two following line are doing exactly the same thing, one using the constants declared in the SDK, the second using the name of the variable as defined in PredefinedVariables.xlsx. You can use either one.
TCPredefinedVariables predefVariables = TCPredefinedVariables.getInstance();
String curVisit = predefVariables.getData(TCConstants.kTCPredefinedVariable_CurrentVisitMs);
String curVisit = predefVariables.getData("#TC_CURRENT_VISIT_MS#");
You can find a full list of variables computed by the SDK, explanations and examples here:
If you want to use Kotlin as your main language, there is absolutely nothing special to do. Compile with the latest versions and call our SDK as usual.
To check an example of how to use this module, please check:
The way we are doing thing in v4 is quite different as we can only send data in post and to TagCommander's servers. But the code didn't change much and we can still use the old basic integration for the v4.
Remove all function not existing anymore like forceReload and the rest should still work. To use new methods you can check in this document how to.
You don't have to update your tagging plan in the application ! You should be able to keep your previous execute as is. What needs to be changed is the container in your TagCommander interface, please check with your consultant.
Support support@commandersact.com
Commanders Act | 3/5 rue Saint Georges - 75009 PARIS - France
This documentation was generated on 19/07/2022 16:25:24