Mobile App Sensor Documentation (English Version)

 

Version:

1.2.0

Date:

2014-10-01

Author:

Kantar Media spring

eMail:

support@spring.de

Content

Method

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

Release of the Application

Features on Platforms

Description of the Mobile App Library Interface

Properties of the Libraries

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

Description

spring.STARTED

The application has been started.

spring.FOREGROUND

The application was brought to the foreground or has received the focus.

spring.BACKGROUND

The application was brought into the background or does no longer have the focus.

spring.CLOSED

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:

 

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

 

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:

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.

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

/*
 * 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 (default: 30 seconds)

With this value, a timeout (in 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=spring.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=spring.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=spring.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,  we have prepared different url Schemes for our clients (please check this with our Customer Support Team). 

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 *** with the url Scheme assigned for your company,
										please contact us for such info if you didn't receive.
			</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 (<site>) 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);

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);

 

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: (warning) 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