1 About this integration guide

This integration guide provides all of the information required for technical integration and use of the ÖWA library in apps that use the Android operating system. The app platform supported here is Android version 5.0 and above.

2 ÖWA library (Android)

The ÖWA library for Android provided by INFOnline (also referred to hereafter as “IOLib”) is a software library that records and saves information about the use of Android apps and sends it to an appropriate backend for validation and monitoring.

2.1 Provision

The IOLib Android is made available by ÖWA for download. The download includes:

  • the release notes as a text file
  • the change log as a text file
  • the Android library as a binary distribution (.aar)
  • an Android studio project “INFOnlineLibSample”: a sample app with integrated IOLib

2.2 Requirements

The ÖWA library for Android supports integration via the “Android Studio” development environment with Windows/macOS or Linux.

2.2.1 Development environment

The following prerequisites must be in place to complete integration of the IOLib:

  • Android SDK Releaser 24 or higher
  • Android Studio 3.0 or higher
  • Google Play Services 10 or higher

Android apps that use the IOLib must be compiled with Android 5.0 (API Level 20) as a minimum. The minimum SDK Version in the manifest is therefore 20.


The IOLib compiles with Android SDK r26. Android apps that compile with older Android SDK versions by using ProGuard will possibly get the following warning:

Warning: de.infonline.lib.IOLWebViewClientV24: can't find referenced method 'boolean shouldOverrideUrlLoading(android.webkit.WebView,android.webkit.WebResourceRequest)' in library class android.webkit.WebViewClient

You can ignore that warning using the ProGuard directive '-dontwarn android.webkit.WebViewClient', as the missing reference has not been added until Android SDK r24.

2.2.2    Operating system

The IOLib Android requires Android 5.0 or higher to operate.

2.2.3    Compatibility

A new version of the Android operating system may require an update to the library.
It may not be possible to guarantee complete upward compatibility under some circumstances.

2.3 Function

2.3.1    When must the library be accessed?

Accessing the functions of the IOLib within the app is linked to certain events. Specifications or recommendations about the point in the app or the user actions at which the ÖWA library should be accessed and which information should be transferred have been formulated by ÖWA for app providers.
The specifications for accessing the IOLib within the app are described in section 4 (Specifications for accessing the ÖWA library).

2.3.2   Transmission of the measurement data

The transmission of the data itself takes place asynchronously. This avoids delaying or blocking the user’s interaction with the app.

3 Integration of the ÖWA library Android

This section describes the technical integration of the ÖWA library into an Android project structure.

3.1 Thread-safe

The IOLib is thread-safe.

3.2 IOLib files

The ÖWA library for Android comprises the following files

  • RELEASE_NOTES.txt
    This file includes information about the releases of the IOLib.
  • CHANGELOG.txt
    This file includes a history of the changes over the individual releases of the IOLib.
  • „infonlinelib_x.x.x.aar“ file
    The IOLibrary for recording the usage data of an Android app as a binary distribution
  • „INFOnlineLibrarySample“ directory
    A sample project for Android Studio that demonstrates use of the IOLib

3.3 Integration of the IOLib measurement library

Integration of the IOLib into an Android app project is described below.

1.    In Android Studio: Integration of AAR file

  • Copy the file „infonlinelib_X.X.X.aar“ to the project to be measured (e.g. to <MyApp>/app/libs)

2.    In Android Studio: adapt build.gradle

  • Adapt the file <MyApp>/app/build.gradle:
//The directory in which infonlinelib_X.X.X.aar is located must be specified as the repository

repositories{
  flatDir{
   dirs 'libs'
  }
}
dependencies {
  //INFOnline Library requires the Google Play Services Library   implementation 'com.google.android.gms:play-services-ads:11.8.0'

  //Link the INFOnline library
  implementation 'de.infonline.lib:infonlinelib_X.X.X@aar'
}

3.  In Android Studio: Initializing IOLib

  • Create a new class and derive from application or use an existing class
  • Initialize IOLib (described below)

The IOLib should be initialised in the onCreate() method of the application!

The IOLib offers two different options for initialization:

1) Initializing the app with implicit session start:

import de.infonline.lib.IOLSession;
import de.infonline.lib.IOLSessionType;
import de.infonline.lib.IOLSessionPrivacySetting;
import android.app.Application;

public class SampleApplication extends Application {

   @Override
   public void onCreate() {
      super.onCreate();
      IOLSession.getSessionForType(IOLSessionType.OEWA)// Session Type OEWA
          .initIOLSession(this, // Application Context
             "OfferIdentifier", // Offer Identifier
             BuildConfig.DEBUG, // Debug mode on/off
             IOLSessionPrivacySetting.LIN); // Debug modePrivacy Setting on/off
   }
}

ALTERNATIVELY, the lib can also be initialized in 2 steps and the session can be started:

2) The pure initialization of the IOLib:

import de.infonline.lib.IOLSession;
import android.app.Application;

public class SampleApplication extends Application {

   @Override
   public void onCreate() {
      super.onCreate();
      IOLSession.init(this) // Application Context
   }
At runtime then the initialization of the session:

public void initIOLSession() {
   IOLSession.getSessionForType(IOLSessionType.OEWA) // Session Type OEWA
      .initIOLSession("OfferIdentifier", // Offer Identifier
         BuildConfig.DEBUG, // Debug mode on/off
         IOLSessionPrivacySetting.LIN); // Privacy Setting
}

4. In Android Studio: Code

  • IOLib can be stopped and started explicitly

IOLSession.getSessionForType(IOLSessionType.OEWA).startSession();
IOLSession.getSessionForType(IOLSessionType.OEWA).terminateSession();

This works only if the IOL session was initialised in the onCreate() method of the application! The method is described in section 3.3 / point 3.

5.  In Android Studio: Every Activity

  • Events are logged via the IOLSession.
  • Events can be logged in the activities of the app, e.g. accessing a ViewAppeared

// Tracking View AppearedIOLSession.getSessionForType(IOLSessionType.OEWA)
  .logEvent(new IOLViewEvent(IOLViewEventType.appeared));

3.4 Integration of the Google Play Services Library

As of August 2014, polices of the Advertising Identifier must be used in relation to audience measurement in accordance with the provisions of the Google Play Developer Program:

https://play.google.com/about/monetization-ads/ads/ad-id/

In order to record the Advertising Identifier, the Google Play Services library must be integrated into the project, but only the Google Mobile Ads API:

dependencies {
  implementation 'com.google.android.gms:play-services-ads:11.8.0'
}

However, the Advertising Identifier can only be read on devices that have Google Play installed.

Google provides a detailed guide that describes step by step how the library is integrated into the project concerned:

http://developer.android.com/google/play-services/setup.html


Integration of the Google Play Services library must also be carried out for apps that are not published in the Google Play Store!

3.5 Parallel measurement ÖWA and INFOnline (IVW, AGOF)

The IOLib Android supports the parallel operation of sessions of different measurement systems. In the following it shall be shown how both measurements can be operated simultaneously.

Prerequisite is an integration of the IOLib Android according to chapter 3.3. The points 3-5 have to be executed as follows:

3.  In Android Studio: Initialise the IOLib:

The IOLib offers two different options for initialization:

1) Initializing the app with implicit session start:

import de.infonline.lib.IOLSession;
import de.infonline.lib.IOLSessionType;
import de.infonline.lib.IOLSessionPrivacySetting;
import android.app.Application;

public class SampleApplication extends Application {

  @Override
  public void onCreate() {
    super.onCreate();
    IOLSession.getSessionForType(IOLSessionType.SZM) // Session Type SZM
      .initIOLSession(this, // Application Context
              "OfferIdentifier-SZM", // Offer Identifier SZM
              BuildConfig.DEBUG, // Debug mode on/off
              IOLSessionPrivacySetting.LIN); // Privacy Setting

    IOLSession.getSessionForType(IOLSessionType.OEWA) // Session Type ÖWA
      .initIOLSession(this, // Application Context
              "OfferIdentifier-OEWA", // Offer Identifier ÖWA
              BuildConfig.DEBUG, // Debug mode on/off
              IOLSessionPrivacySetting.LIN); // Privacy Setting
}

ALTERNATIVELY the lib can also be initialized in 2 steps:

2) The pure initialization of the IOLib:

import de.infonline.lib.IOLSession;
import android.app.Application;

public class SampleApplication extends Application {

  @Override
  public void onCreate() {
    super.onCreate();
    IOLSession.init(this) // Application Context
  }
At runtime, the session is initialized for both measurement systems:

public void initIOLSession() {

  IOLSession.getSessionForType(IOLSessionType.SZM) // Session Type SZM
    .initIOLSession("OfferIdentifier-SZM", // Offer Identifier SZM
              BuildConfig.DEBUG, // Debug mode on/off
              IOLSessionPrivacySetting.LIN); // Privacy Setting

  IOLSession.getSessionForType(IOLSessionType.OEWA) // Session Type ÖWA
    .initIOLSession("OfferIdentifier-OEWA", // Offer Identifier ÖWA
              BuildConfig.DEBUG, // Debug mode on/off
              IOLSessionPrivacySetting.LIN); // Privacy Setting
  }

4. In Android Studio: Code

  • Explicitly start IOLib for both active sessions
IOLSession.getSessionForType(IOLSessionType.SZM).startSession();
IOLSession.getSessionForType(IOLSessionType.OEWA).startSession();

This only works if the IOLSession has been initialized in the onCreate () method of the application! The method 1) is described in chapter 3.3 / Pkt.3.

5. In Android Studio: Every Activity

  • Events are logged via the IOLSession, in each case into the selected measuring system.
  • Events can be logged in the app's activities, e.g. the call of a ViewAppeared
// Tracking View Appeared
IOLSession.getSessionForType(IOLSessionType.SZM)
  .logEvent(new IOLViewEvent(IOLViewEventType.appeared));

IOLSession.getSessionForType(IOLSessionType.OEWA)
  .logEvent(new IOLViewEvent(IOLViewEventType.appeared));

3.6 IOLib functions

The IOLib offers the functions described below:

3.6.1  Use of IOLib in OEWA mode

IOLSession getSessionForType(IOLSessionType iolSessionType)

Functions of the IOLib must be called on a concrete IOLSession. To do this, pass the appropriate IOLSessionType.
Parameter:

  • IOLSessionType (mandatory)
    The desired IOLSessionType.

Example:

IOLSession iolSession = IOLSession.getSessionForType(IOLSessionType.OEWA);

3.6.2  Initialisation

initIOLSession(String offerIdentifier, boolean debugModeEnabled, IOLSessionPrivacySetting privacySetting)

initIOLSession(Context context, String offerIdentifier, boolean debugModeEnabled, IOLSessionPrivacySetting privacySetting)


The IOLib must be initialised before recording of the events. In doing so, the site ID of the app must be transferred as a parameter.

Paremeter:

  •    Application Context (optional)

The Application Context of the Android app must be transferred here, if not already done via IOLSession.init (Context context).

  •    Site ID (mandatory)

The unique service ID for the relevant app is asigned by ÖWA for each app and each operating system.

  •    debugModeEnabled (optional)

When debug mode is activated, the measurement library logs under the logcat tag “INFOnline”. It is recommended that the value “BuildConfig.DEBUG” is passed here.

The default value is false if no value is transferred.

  •     Privacy setting (mandatory)

Declaring the legal basis for the measurement. In case of the ÖWA always LIN.

Example:

IOLSession.getSessionForType(IOLSessionType.OEWA)
  .initIOLSession(this, // Application Context
      "OfferIdentifier", // Offer Identifier
      BuildConfig.DEBUG); // Debug mode
      IOLSessionPrivacySetting.LIN); // Privacy Setting LIN

3.6.3 Logging an event

The measurement data is recorded by means of the logEvent call. An instance of the event class to be measured is passed.

logEvent(IOLEvent event)


Parameter:

  •     Event (mandatory)

The event to be recorded.

3.6.4 Instantiation of an event class

IOLEvent(EventType eventType, String category, String comment, Map<String, String> params)

Parameter:

  •     EventType (mandatory)

The event to be recorded. The individual events can assume different states. Thus, a download can e.g. started, aborted by the user, successfully completed or terminated incorrectly.
For some events, the type parameter is omitted because only one valid type is defined for these events. The IOLCustomEvent requires the freely definable string parameter name instead of a type.

  •     Category (optional): Contentpath

The content code is transferred in the “category” parameter. This code is set by the provider. The code is used to identify the content displayed.
Using the guidelines described in the following section, the provider decides whether an event constitutes a valid PI as defined by the ÖWA guidelines. If an event does fall under the definition of a valid PI, it is essential to provide a contentpath. If an event does not constitute a valid PI, nil should be transmitted. This field is limited to 255 characters.

  •     Comment (optional): Comment

Comment field. This field is not limited in length. Transfer of this value is optional; if it is not defined, it should not be transferred.

  •     params (optional): Parameter

A hash map with freely definable additional information about the event. Key and Value must be of type String, their maximum length is limited to 255 characters each. Passing this value is optional.

Available Events

The IOLib provides the following IOLEvent-derived event classes with the associated types:

  •     IOLViewEvent

    • IOLViewEventType.Appeared

Examples:

IOLEventType.ViewAppeared

public class SampleActivity extends Activity {

   @Override
   protected void onResume() {
      super.onResume();
      IOLEvent event = new IOLViewEvent(
         IOLViewEvent.IOLViewEventType.Appeared,
         "category",
         "comment");
      IOLSession.getSessionForType(IOLSessionType.OEWA).logEvent(event);
      // Other Code ..
   }
}

3.6.5  Sending the measurement data

sendLoggedEvents()

The IOLib controls sending of the measurement data independently and entirely transparently. sendLoggedEvents may be accessed to force sending of the data. The IOLib then attempts to send the measured data immediately or to resend it, as soon as a data connection has been established.

Parameter:

  • -

Example:

IOLSession.getSessionForType(IOLSessionType.OEWA).sendLoggedEvents();

3.6.6  Debug mode

setDebugModeEnabled(boolean enable);

The measurement library can be put into debug mode. Various outputs in the log flow are generated here (errors, warnings, information, events and requests).

The default value is false if the measurement library was initialised with IOLSession.initIOLSession(Context context, String offerIdentifier).

Parameter:

  • boolean enable

Possible values: true|false

Example:

IOLSession.setDebugModeEnabled(true);

3.6.7  Terminate session

terminateSession()

The active IOLib session can be terminated explicitly. This facilitates an opt-out during the app runtime. The data collected up to that point is discarded and will not be sent.


Only use with opt-out by the user!

Parameter:

  • -

Example:

IOLSession.getSessionForType(IOLSessionType.OEWA).terminateSession();

Session does not then have to be re-initialised, but can be started at any time with startSession()!

3.6.8  Start session

startSession()

If the active session of the IOLib was terminated explicitly, it can be re-started at any time with startSession(). Re-initialisation is not necessary.

Parameter:

  • -

Example:

IOLSession.getSessionForType(IOLSessionType.OEWA).startSession();

3.6.9  Integration of the opt-out function

Implementation is in the responsibility of the developer of the app concerned and, if activated by the user, it should lead to the ÖWA library either not being initialised at all or the running session being terminated explicitly. The procedure is described in section 3.6.7 (Terminating a session).

On integration of the function, users of the app can activate and deactivate the opt-out. When the opt-out is activated, no counter impulse is triggered.


If the running session is terminated explicitly, all of the measurement data recorded up to this point but not yet sent is discarded.

If the opt-out is revised, the measurement library should be restarted. The procedure is described in section 3.6.8 (Starting a session).

3.7 Debug information

The library can be put into debug mode for the purposes of general error analysis and in particular to send the measurement data. In this debug mode, the library generates various outputs in the log flow (console): errors, warnings, information, events and requests.

These outputs can then be filtered easily on the console.

In order to put the IOLib into debug mode, the setDebugModeEnabled method is accessed:

IOLSession.setDebugModeEnabled(true);

Debug mode is deactivated by default unless the debug mode was explicitly activated on initialisation. The procedure is described in section 3.6.2 (Initialisation).


Please deactivate debug mode before publishing the app.

3.8 Android TV / Nexus Player

The IOLib Android is completely suitable for the measurement of an Android app on the ‘Android TV / Nexus Player’ platform, as it technically concerns the same operating system as other Android devices.

If you want to use the IOLib Android among Android TV / Nexus Player, please make sure to follow the integration steps according to chapter 3.3. Regarding the methods for managing the IOLib, please use the handling given in chapter 3.6.

3.9 Fire OS

In principle, the IOLib is suitable for the measurement of an Android app on the ‘Fire OS 5’ operating system. But this compatibility only applies to the publishing of a native Android app on Fire OS 5, not on HTML5/WebApps.

If you want to use the IOLib Android among Fire OS 5, please make sure to follow the integration steps according to chapter 3.3. Regarding the methods for managing the IOLib, please use the handling given in chapter 3.6.


Currently, there is no provision of Second Screen measurement in conjunction with the Amazon Fling SDK.

4 Requirements for accessing the library

4.1 General information

Recording of the app usage by the user is carried out by the app accessing the ÖWA library when defined events take place that characterise a user interaction. The user interaction is referred to as an event.


The ÖWA library must be accessed explicitly by the app when the event occurs.

4.1.1    Interpretation of events as valid PIs

The specifications listed below define how the ÖWA library is to be used in the context of the ÖWA app measurement.

PI-Events

With PI events, the event is used to generate a page impression in the same way as for the ÖWA web measurement. A contentpath must be assigned to this event (hereafter simply referred to as a “CP”). This CP can subsequently be allocated to various categories and serves as the basis for creating booking units. With PI events the ÖWA's specifications for page impressions must be attended.

4.2 Guidelines for allocation of the contentpath

For PI events, the CP must be given as a unique identifier of the content displayed. This CP is specified by the app provider.

When specifying the contentpath, the ÖWA CP-guidelines must be attended:

- Length: A CP may contain a maximum of 255 characters

- Number: A maximum of 15.000 different CPs may be used

- Permitted characters: a-z, A-Z, 0-9; comma „,“; hyphen „-“; underscore „_“; slash „/“

Detailed information of the ÖWA CP-guidelines can be found at:

http://www.oewa.at/fileadmin/Documents/documents/implementierung/oewaInfo_kategoriensystem_v1_0_1.pdf