Mobile App Sensor Documentation (English Version)

Mobile App Sensor Documentation (English Version)

Mobile App Sensor Documentation (English Version) Version: 1.2.1 Date: 2015-03-25 Author: email: Kantar Media spring support@spring.de Content Mobile App Sensor Documentation (English Version) Method Information for Developers Integration of Libraries Integration of libraries with ios Integration of library with Android Release of the Application Features on Platforms Offline-Mode ios Android Description of the Mobile App Library Interface Properties of the Libraries Predefined Variables The variable: Action (ac) Implementation of an app page request via the action variable (ac) Information (optional) Opt-Out Mobile Support Supported Platforms Implementation ios Example Timeout Debug Implementation of the URL Scheme in ios Implementation Android Example Managing Lifecycle Events in Android Apps Android Permissions Timeout Advise for Implementation when using Android 3.0 and higher Versions Note: Starting from Android 3.0 Implementation Blackberry Implementation Windows Phone Implementation Titanium Method The Mobile App Sensor can be used for different mobile devices. The library thereby only measures actions within applications. This Sensor does not measure the web usage of a mobile device. For this a different implementation is available (Mobile Sensor), which needs to be included into the respective websites directly. With the standard procedure a comprehensive tracking of applications and mobile web usage is not possible. Information for Developers All spring sensors capture the events in the moment in which they arise. This concept is also implemented in the libraries for the apps, that means that all actions are sent immediately. In case of any questions concerning this, please contact our support team under support@spring.de.

Integration of Libraries It could be demanded that the app needs to be measured on several markets. In this case the most recent version of the Mobile App Sensor needs to be integrated for every single market with the corresponding implementation instructions. Spring measurement libs for variant clients had been unified to one, and of course the customized settings are applied based on the different domains internally. From version 1.1.0 on this is supported through a different naming and a changed package structure. In the following examples are the libs for market MA and market MB. Concerning the naming the following structure must be used spring-appsensor-<os>-<market>-<version> Examples: spring-appsensor-ios-ma-1.1.0.zip spring-appsensor-android-mb-1.1.0.zip The zip file we released will contain the spring measurement lib, possibly the necessary utility lib and corresponding API doc. Please consider the implementation instructions of the single libraries. Those may be differ (strongly) on the single markets. Integration of libraries with ios In the following example the library of the markets MA is integrated. The header file is needed: Spring.h

#import "TestApp.h" #import "Spring.h" @implementation TestApp3AppDelegate @synthesize window = _window; @synthesize tabbarcontroller = _tabbarcontroller; Spring *spring; - (BOOL)application:(UIApplication *)application didfinishlaunchingwithoptions:(nsdictionary *)launchoptions { // --- MA --------------------------------------------------------------------------------- spring = [[Spring alloc] initwithsiteandapplication:@"site" application:@"applicationname"]; NSMutableDictionary *dict = [NSMutableDictionary dictionarywithobjectsandkeys:spring_app_started, SPRING_VAR_ACTION,nil]; [spring commit:dict]; self.window.rootviewcontroller = self.tabbarcontroller; [self.window makekeyandvisible]; return YES; //... more code Integration of library with Android In the following example the library of themarkets MA is integrated. The corresponding java Class in jar file is needed: de.spring.mobile.springmobile

package de.spring.android.test; import java.util.hashmap; import java.util.map; import de.spring.mobile.springmobile; import android.app.activity; public class MyActivity extends Activity { SpringMobile ma; public MyActivity() { ma = new SpringMobile("site", "applicationname", getapplicationcontext()); * @see android.app.activity#onstart() @Override protected void onstart() { Map<String, Object> mapma = new HashMap<String, Object>(); mapma.put(springmobile.var_action, SpringMobile.APP_STARTED); ma.commit(mapma); // more code... Release of the Application The developer should make sure that, before the application goes into the release process, the latest version of the spring library is used (see your specific customer download page). Features on Platforms Offline-Mode For Android and ios version, spring-lib has a feature the so-called "offlinemode". This mode can be switched on and off by using public API: setofflinemode (boolean offlinemode) If the lib is configured to offlinemode, spring library will hold all requests in a local buffer and send them when the device goes back online. The spring-lib checks the Internet connection regularly by using the Android/iOS Timer and sends the data as soon as possible. Please notice: Old requests will be dropped if too many requests pump into local buffer for the limitation in buffer size. The default buffer size is 500. The data will be stored in a local file, so the lib will not lose the requests even if the application terminates

the spring-lib tries to send the requests in a fixed rate, 10 seconds by default, and sends them if device is online again ios Identifiers on ios Device ID (did) Advertising ID (ai) Mac ID (mid) ID_For_Vendor (ifv) ios4 --- --- --- ios5 --- --- --- ios6 --- ios7 --- --- ios8 --- --- Considering that the Apple private policy is changing all the time, Spring libs have to adapt different UDIDs for identifying the end user's devices. Since ios7 the Mac ID is not available anymore, Since ios7 introducing of Advertising ID and ID_For_Vendor Please attention: Apple will reject all the applications which retrieve Advertising ID (ai) but with no advertising content provided. So Advertising-Framework is linked as optional in Spring lib, If the Advertising ID should be used as udid, please import Advertising-Framework into your projects. Android Google Advertising ID Beginning with Spring lib 1.6.0, GoogleAdvertisingID is adapted to identify the android devices. In order to achieve this, please import google-play-services_lib to your application. Follow the tutorial detailed info: http://developer.android.com/google/play-services/setup.html Install the Google Play Services SDK. Import the project into your application. Don't forget to add following items into your project AndroidManifest.xml file: <meta-data android:name= "com.google.android.gms.version" android:value= "@integer/google_play_services_version" /> Description of the Mobile App Library Interface This chapter describes the interface of the Mobile App Sensor exemplarily for all platforms. For explanation the pragramming language java is used. However the function names are the same in any supported platform and their programming language.

public class SpringMobile { Is sent when the application is started. public static final String APP_STARTED = "spring.started"; Is sent when the application is put into the background. public static final String APP_BACKGROUND = "spring.background"; Is sent when the application is taken into the foreground. public static final String APP_FOREGROUND = "spring.foreground"; Is sent when the application is closed or finished. public static final String APP_CLOSED = "spring.closed"; The variable for the sending of activities public static final String VAR_ACTION = "ac"; * Constructor with mandatory declaration of a website identification * and the application name. public SpringMobile(String site, String application) { * By calling this method, all the name-value-pairs * of the {@ link map are sent to the measuring system. * * @param target A map with all name-value-pairs. public void commit(map<string,string> target) { * When the value <code>false</code> is specified, * the sending of requests to the measuring system is switched off * This value is <code>true</code> by default. public void settracking(boolean tracking) { * Delivers the value <code>true</code> when the tracking * is activated, otherwise the value is <code>false</code>. public boolean istracking() { The interface is basically the same on all platforms. The specifics and an example code can be found in the corresponding chapters on the platforms. For the installation generally applies: Create an object SpringMobile with the application name and the website name. (The website name is provided with the library) For defined actions, call the method commit(...) with the appropriate variables and values. Properties of the Libraries Property default OS Description timeout 10 sec all This timeout is set on the HTTP-Connections, that sends an action to the measuring system.

Predefined Variables Out of the application, an HTTP request has to be sent to the measuring system. Variable Mandatory Description ac No The action that has been executed. The variable: Action ( ac) By using this variable, the measuring system can be informed, which actions have been executed in the application. Currently, the following actions are understood: Variable spring.started spring.foreground spring.background spring.closed Description The application has been started. The application was brought to the foreground or has received the focus. The application was brought into the background or does no longer have the focus. The application has been stopped. Implementation of an app page request via the action variable (ac) By using the variable ac, the execution of a content page within an application can be measured also. Permitted characters are: a-z A-Z 0-9 Comma, Point. Dash - and Underscore _ Slash "/" is used as separator for hierarchy levels The assignment of content and construction of booking units is in the responsibility of the supplier/marketer. Example for this variable are sport_football mainpage 200_543 Information (optional) The user can be informed at some point that the application monitors the user actions and transmits them to a measuring system. Furthermore, the user must be informed that he has the possibility to switch of the tracking in the application and can contradict this way. (see: Opt-Out) For this purpose, you can include data privacy information in your language into an appropriate place of your app implementation:...... Mobile App Sensor Measurement: On/Off Opt-Out The application developer can give users the ability to stop the further tracking of the user actions. For this purpose the library offers the following methods:

* When the value <code>false</code> is specified, the sending of * requests to the measuring system is switched off. * This value is <code>true</code> by default. public void settracking(boolean tracking) { * Delivers the value <code>true</code> when the tracking * is activated otherwise the value is <code>false</code>. public boolean istracking() { A persistent saving of the opt-out decision in the library is not provided and needs to be implemented by the app developer. Mobile Support Should you encounter any issues or problems during the implementation, please send an email to our support team under support@spring. de with the following information: Name Description of the problem Possibly error messages with error codes Platform (version), application name (version) Supported Platforms Implementation ios The following example shows the basic installation for the ios platform. When generating the class SpringMobile a site identifier (<site> ) has to be indicated, which is shipped together with this documentation and the libraries. Please note! At the application start the Spring object has to be instanced one-time and to be used for the whole life cycle of the application Example

* Importing SpringMobile #import "Spring.h" * Providing entity Spring *spring; * Generating SpringMobile entity with site id and * application name spring = [[Spring alloc] initwithsiteandapplication:@"<site>" application:@"myapplication1"]; * Sending the start of the application to the measurement system NSMutableDictionary *dict = [NSMutableDictionary dictionarywithobjectsandkeys:app_started,var_action,nil]; [spring commit:dict];... // OR * Sending the action spring.background NSMutableDictionary *dict = [NSMutableDictionary dictionarywithobjectsandkeys:app_background,var_action,nil]; [spring commit:dict]; Example: Implementation of an app page request via the action variable (ac)

* Importing SpringMobile #import "Spring.h" * Providing entity Spring *spring; * Generating SpringMobile entity with site id and application name spring = [[Spring alloc] initwithsiteandapplication:@"<site>" application:@"myapplication1"]; * Sending AC to the measurement system NSMutableDictionary *dict = [NSMutableDictionary dictionarywithobjectsandkeys:@"mainpage",@"ac",nil]; [spring commit:dict];... Timeout With this value, a timeout (in seconds = default: 30 seconds)) for each HTTP request can be configured within the library. Example: spring = [[Spring alloc] initwithsiteandapplication:@"app" application:@"test App"]; spring.timeout = 30.0; // in seconds Debug If this value is set on YES, the library provides debug outputs over the class NSLog. spring = [[Spring alloc] initwithsiteandapplication:@"app" application:@"test App"]; spring.debug = YES; Output example:

2011-11-25 13:42:52.878 TestApp3[73923:ff07] spring (1.0.3.1)> http://test.2cnt.net/j0=,,,;+,app=test%20app+did=7ca359bc4c3c6a19;;;?lt =gvf6lykt 2011-11-25 13:42:52.927 TestApp3[73923:ff07] spring (1.0.3.1)> http status code: 200 - no error 2011-11-25 13:42:56.521 TestApp3[73923:1020b] spring (1.0.3.1)> http://test.2cnt.net/j0=,,,;+,app=test%20app+did=7ca359bc4c3c6a19+ac=sp ring.background;;;?lt=gvf6m1e1 2011-11-25 13:42:56.559 TestApp3[73923:1020b] spring (1.0.3.1)> http status code: 200 - no error 2011-11-25 13:42:59.388 TestApp3[73923:10013] spring (1.0.3.1)> http://test.2cnt.net/j0=,,,;+,app=test%20app+did=7ca359bc4c3c6a19+ac=sp ring.foreground;;;?lt=gvf6m3lo 2011-11-25 13:42:59.427 TestApp3[73923:10013] spring (1.0.3.1)> http status code: 200 - no error 2011-11-25 13:43:04.554 TestApp3[73923:11f0b] spring (1.0.3.1)> http://test.2cnt.net/j0=,,,;+,app=test%20app+did=7ca359bc4c3c6a19+ac=sp ring.background;;;?lt=gvf6m7l5 Implementation of the URL Scheme in ios Generally for spring measuring purpose, only some modifications need to be applied in your App, if a Panel App is used in your market. (This blog may assist your implementation): Register the URL Scheme accordingly. In order to register your URL Scheme into your ios App, you need to edit the Info.plist file under the "Supporting Files" in your project folder, two ways: 1. you can edit it in any editor, if you do so, please insert the following code: <key>cfbundleurltypes</key> <array> <dict> <key>cfbundleurlname</key> <string>***</string> //please change *** to your URL name, not so important <key>cfbundleurlschemes</key> <array> <string>***</string> //very important, please replace </array> </dict> </array> 2. Or you can edit this in xcode, add an item into Info.plist, named "URL types", expand "Item 0" under "URL types", and add two items: "URL identifier", "URL Schemes". For "URL identifier", assign your identifier, and for "URL Schemes", add a new item within it named "Item0", REGISTER A UNIQUE URL SCHEME FOR YOUR APP, VERY IMPORTANT! It should be like the following:

Implementation Android The following example shows the basic installation for the Android platform. When generating the class SpringMobile a site identifier (<s ite>) has to be indicated, which is shipped together with this documentation and the libraries. Example * Importing SpringMobile import de.spring.mobile.springmobile; * Generating SpringMobile entity with site id and * application name SpringMobile spring = new SpringMobile("<site>", "Application Name", getapplicationcontext()); * Sending the start of the application to the measurement system Map<String, Object> map = new HashMap<String, Object>(); map.put(springmobile.var_action, SpringMobile.APP_STARTED); spring.commit(map); * Sending the action spring.background Map<String, Object> map = new HashMap<String, Object>(); map.put(springmobile.var_action, SpringMobile.APP_BACKGROUND); spring.commit(map); Managing Lifecycle Events in Android Apps A helper class for the Activities can be used instead of SpringMobil. Link: http://developer.android.com/reference/android/app/activity.html Example Activity: import android.app.activity; import android.os.bundle; public class TestActivity extends Activity { private SpringMobileHelper springhelper; @Override public void oncreate(bundle savedinstancestate) { super.oncreate(savedinstancestate); setcontentview(r.layout.main); springhelper = SpringMobileHelper.getInstance(getApplicationContext()); @Override protected void onstart() { super.onstart(); springhelper.start(); @Override

protected void onresume() { super.onresume(); springhelper.resume(); @Override protected void onpause() { super.onpause(); springhelper.pause(); @Override protected void ondestroy() { super.ondestroy(); springhelper.destroy(); Helper Class: import java.lang.thread.state; import java.util.hashmap; import java.util.map; import android.content.context; import de.spring.mobile.springmobile; This class will help to manage more than one Activity. The Class holds the SpringMobile object and managed the events to it. public class SpringMobileHelper { private static SpringMobileHelper singelton = null; private SpringMobile spring = null; private boolean isstarted = false; private int foregroundcounter = 0; private final Thread sendbackground = new Thread() { @Override public void run() { super.run(); while(true) { synchronized(sendbackground) { try { wait(); catch (InterruptedException e) { continue; try { sleep(1000); Map<String, Object> map = new HashMap<String, Object>(); map.put(springmobile.var_action, SpringMobile.APP_BACKGROUND); spring.commit(map); catch (InterruptedException e) { ; {sendbackground.start(); private SpringMobileHelper() { * @param the context @return SpringMobileHelper public static SpringMobileHelper getinstance(context context) Unknown macro: { if(singelton == null) { singelton = new SpringMobileHelper(); singelton.spring = new SpringMobile("app", "MoreActivities", context); return singelton;

call by start of activity public void start() Unknown macro: { if(!isstarted) { isstarted = true; Map<String, Object> map = new HashMap<String, Object>(); spring.commit(map); call by resume of activity public void resume() Unknown macro: { foregroundcounter++; if(sendbackground!= null && sendbackground.getstate()!= State.WAITING) { sendbackground.interrupt(); else { Map<String, Object> map = new HashMap<String, Object>(); map.put(springmobile.var_action, SpringMobile.APP_FOREGROUND); spring.commit(map); * call by pause of activity public void pause() { foregroundcounter--; if(sendbackground!= null && sendbackground.getstate()!= State.WAITING) { sendbackground.interrupt(); synchronized(sendbackground) { sendbackground.notify(); call by destroy of activity public void destroy() { if(foregroundcounter == 0) { try { sendbackground.join(1000); Map<String, Object> map = new HashMap<String, Object>(); map.put(springmobile.var_action, SpringMobile.APP_CLOSED); spring.commit(map); catch (InterruptedException e) {

Example: Implementation of an app page request via the action variable (ac) * Example AC import de.spring.mobile.springmobile; * Generating SpringMobile entity with site id and application name SpringMobile spring = new SpringMobile("<site>", "Application Name", getapplicationcontext()); * Sending AC to the measurement system Map<String, Object> map = new HashMap<String, Object>(); map.put("ac", "Mainpage"); spring.commit(map); Android Permissions The following settings need to be conducted in the file AndroidManifest.xml AndroidManifest.xml: <uses-permission android:name="android.permission.read_phone_state"> </uses-permission> <uses-permission android:name="android.permission.internet"> </uses-permission> <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" /> The setting of the permission through the user is not mandatory, but highly recommended. If the permission READ_PHONE_STATE is set, the device ID and the Android ID are used. If the permission is not set, only the Android ID is used. The last one item above is for the registration of google-play-services, which is precondition for retrieving Google Advertising ID. Two aspects are crucial: The Android ID is only recognized if the user disposes of a Google account. (This should be the case for all users of the apps, because it is not possible to access the Android Market without a Google account.) There is a bug in the Android version 2.2, which only occurs in connection with certain providers, where for all affected devices the same Android ID will be delivered. For the study, this would mean that the user identification would become much more difficult. Timeout With this value, a timeout (in seconds) for each HTTP request can be configured within the library.

SpringMobile spring = new ("app","testapp",getapplicationcontext()); spring.settimeout(30); // in seconds Advise for Implementation when using Android 3.0 and higher Versions Note: Starting from Android 3.0 Since Android 3.0 network accesses are not allowed from the main thread anymore. Thus, the Spring.commit () method is achieved in a background thread. For this reason, please keep the initialization and usage of Spring lib in your main UI thread, Spring lib will not block your GUI display. Otherwise background thread conflicts might pop up. Implementation Blackberry The following example shows the basic installation for the Blackberry platform. When generating the class SpringMobile a site identifier (<site>) has to be indicated, which is shipped together with this documentation and the libraries.

* Importing SpringMobile import de.spring.mobile.springmobile; * Generating SpringMobile entity with site id and * application name SpringMobile spring = new SpringMobile("<site>", "myapplication1"); * Sending the start of the application to the measurement system Hashtable target = new Hashtable(); target.put(springmobile.var_action, SpringMobile.APP_STARTED); try { //... spring.commit(target); catch (ParamNotSupportedException e) { e.printstacktrace(); catch (IOException e) { e.printstacktrace(); * Sending the action spring.background Hashtable target = new Hashtable(); target.put(springmobile.var_action, SpringMobile.APP_BACKGROUND); try { spring.commit(target); catch (ParamNotSupportedException e) { e.printstacktrace(); catch (IOException e) { e.printstacktrace(); * Alternative method * Sending the action spring.background with own * connection parameters Hashtable target = new Hashtable(); target.put(springmobile.var_action, SpringMobile.APP_BACKGROUND); Hashtable bbprops = new Hashtable(); bbprops.put("deviceside", "true"); try { spring.commit(bbprops,target); catch (ParamNotSupportedException e) { e.printstacktrace(); catch (IOException e) { e.printstacktrace();

Example: Implementation of an app page request via the action variable (ac) * example AC Hashtable target = new Hashtable(); target.put("ac", "Mainpage"); try { //... spring.commit(target); catch (ParamNotSupportedException e) { e.printstacktrace(); catch (IOException e) { e.printstacktrace(); Although the library provides the possiblity of using connection parameters, it is highly recommended to use "spring.commit(hashtable target)". While setting the connection parameters (alternative method) changes on high sensitive parts of the library are done. Therefore it is explicitly indicated, that the respective developers are responsible for the correct usage of the library and the correct settings of the connection parameters. While using connection parameters that are not supported a respective exception is thrown. As soon the first parameter is indicated within the Blackberry-Connection-Properties- Hashtable (Hashtable bbprops), the automatic search for a functioning connection is stopped. If using the alternative method "spring.commit(hashtable bbprops, Hashtable target)" it is assumed, that this was tested for all possible devices and connections. Implementation Windows Phone The following example shows the basic installation for the Windows Phone 7 platform. When generating the class SpringMobile a site identifier (<site>) has to be indicated, which is shipped together with this documentation and the libraries.

* Importing SpringMobile using spring_mobile_wp7; * Generating SpringMobile entity with site id and * application name SpringMobile spring = new SpringMobile("<site>", "myapplication1"); * Sending the start of the application to the measurement system Dictionary<String, String> target = new Dictionary<string, string>(); target.add(springmobile.var_action, SpringMobile.APP_STARTED); spring.commit(target);... * Sending the action spring.background Dictionary<String, String> target = new Dictionary<string, string>(); target.add(springmobile.var_action, SpringMobile.APP_BACKGROUND); spring.commit(target); Example: Implementation of an app page request via the action variable (ac) * Example AC using spring_mobile_wp7; * Generating SpringMobile entity with site id and application name SpringMobile spring = new SpringMobile("<site>", "myapplication1"); * Sending AC to the measurement system Dictionary<String, String> target = new Dictionary<string, string>(); target.add("ac", "Mainpage"); spring.commit(target);... For the measurement we need the device ID. Please set the right for reading the device ID into a config file (WMAppManifest.xml).... <Capabilities>... <Capability Name="ID_CAP_IDENTITY_DEVICE"/>... </Capabilities>...

Implementation Titanium The following example shows the basic installation for the Titanium platform. When generating the object SpringMobile a site identifier (<si te>) has to be indicated, which is shipped together with this documentation and the libraries. * Importing SpringMobile Ti.include("titaniumSpring.js"); * Generating SpringMobile entity with site id and * application name var springmobile = new SpringMobile("<site>", "myapplication1"); var request = new Array(); * Sending the start of the application to the measurement system request[var_action] = APP_STARTED; var sent = springmobile.commit(request); * Example: Sending the action spring.background var request = new Array(); request[var_action] = APP_BACKGROUND; var sent = springmobile.commit(request);