IOMb - IOMbLib Android API¶

The IOMbLibrary Android provides the functions described below for using the IOMb measurement:

Calling the IOMb Session¶

All functions of the IOMb Lib Android described below must be called on the Measurement object on which the session was created.

1
2
3

var IOMBSession : Measurement
IOMBSession = IOMB.createBlocking(setup)
IOMBSession.logEvent(...)

Configuration of a session¶

NOTE: Before initializing an IOMb session, a valid IOMBSetup object must be created.

Parameters:

• Site ID (mandatory).

  A unique identifier of the site of the respective app. The site ID is uniquely assigned by INFOnline per app and per operating system.

• BaseURL (mandatory)

  The BaseURL of the service platform is the registered domain service name as CNAME when hosting the service platform of INFOnline. If you are operating the service platform in self-hosting, set your AAA(A) DNS entry here.

• Hybrid Identifier (optional).

  An optional identifier to link the measurement streams from the native part and Web content in a WebView within an app.

• Customer Data (optional).

  A free field for internal purposes of the provider.

Example:

1
2
3

val setup = IOMBSetup(
            offerIdentifier = "site ID",
            baseUrl = "https://data-ef4e2c0163.example.com")

Initialization of a session¶

The IOMb Lib Android must be started before the events are captured. The site ID of the app as well as a valid baseURL must be set correctly in the IOMb setup object (see above).

A session can be created synchronously (blocking) or asynchronously (on another thread)

parameter:

• IOMBSetup (mandatory)

  An IOMBSetup object must be used for the IOMb measurement.

Example Init Synchron:

1

IOMBSession = IOMB.createBlocking(setup)

Example Init Asynchronous:

1
2
3

IOMB.create(setup).subscribe { it ->
    IOMBSession = it
}

Logging an event¶

The measurement data is recorded by means of the call logEvent. A previously initialized event must be passed.

1

fun logEvent(event: IOLEvent)

To create an event, an initializer of the corresponding IOLEvent subclass must be called. Up to four parameters can be passed, three of which are optional.

1
2
3
4

IOLEvent(identifier: String,
         category: String,
         state: String?,
         comment: String?

The missing values are then supplemented by nil or default values. Some of the events are automatically captured by IOLib.

Parameter:

• EventType (mandatory)

  The event to be captured. The individual events can have different states. For example, a download may have been started, aborted by the user, successfully completed, or terminated with errors. For some events the type parameter is omitted, because only one valid type is defined for these events. For the IOLCustomEvent, the freely definable string parameter name is required instead of a type.

• Category (mandatory)

  The content code is transmitted in the "category" parameter. This page code is defined by the provider itself. The page code is used to identify the content displayed and is assigned to the IVW Category System 2.0 by the provider in the INFOnline Customer Center. The provider uses the guidelines described in the following chapter to decide whether an event constitutes a mobile PI within the meaning of the IVW guidelines. If an event falls under the definition of a mobile PI, it is mandatory to include a content code. If an event does not represent a mobile PI, nil should be passed. The length of this field is limited to 255 characters.

• Comment (optional)

  Comment field. The length of this field is not limited. Passing this value is optional, if it is not defined, it should not be passed.

• Parameter (optional)

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

Available events¶

IOLib provides the following event classes derived from "IOLEvent" with the corresponding types:

• IOLAdvertisementEvent.
  • IOLAdvertisementEventType.Open
  • IOLAdvertisementEventType.Close
• IOLAudioEvent
  • IOLAudioEventType.Play
  • IOLAudioEventType.Pause
  • IOLAudioEventType.Stop
  • IOLAudioEventType.Next
  • IOLAudioEventType.Previous
  • IOLAudioEventType.Replay
  • IOLAudioEventType.SeekBack
  • IOLAudioEventType.SeekForward
• IOLBackgroundTaskEvent
  • IOLBackgroundTaskEventType.Start
  • IOLBackgroundTaskEventType.End
• IOLCustomEvent
  • type omitted
  • instead state (free definable string, limited to 255 characters)
• IOLDataEvent
  • IOLDataEventType.Cancelled
  • IOLDataEventType.Refresh
  • IOLDataEventType.Succeeded
  • IOLDataEventType.Failed
• IOLDeviceOrientationEvent
  • IOLDeviceOrientationEventType.Changed
• IOLDocumentEvent
  • IOLDocumentEventType.Open
  • IOLDocumentEventType.Edit
  • IOLDocumentEventType.Close
• IOLDownloadEvent
  • IOLDownloadEventType.Cancelled
  • IOLDownloadEventType.Start
  • IOLDownloadEventType.Succeeded
  • IOLDownloadEventType.Failed
• IOLGameEvent
  • IOLGameEventType.Action
  • IOLGameEventType.Started
  • IOLGameEventType.Finished
  • IOLGameEventType.Won
  • IOLGameEventType.Lost
  • IOLGameEventType.NewHighscore
  • IOLGameEventType.NewAchievement
• IOLGestureEvent
  • IOLGestureEventType.Shake
• IOLHardwareButtonEvent
  • IOLHardwareButtonEventType.Pushed
• IOLIAPEvent
  • IOLIAPEventType.Started
  • IOLIAPEventType.Finished
  • IOLIAPEventType.Cancelled
• IOLLoginEvent
  • IOLLoginEventType.Succeeded
  • IOLLoginEventType.Failed
  • IOLLoginEventType.Logout
• IOLOpenAppEvent
  • IOLOpenAppEventType.Maps
  • IOLOpenAppEventType.Other
• IOLPushEvent
  • IOLPushEventType.Received
• IOLUploadEvent * IOLUploadEvent**
  • IOLUploadEventType.Cancelled
  • IOLUploadEventType.Start
  • IOLUploadEventType.Succeeded
  • IOLUploadEventType.Failed
• IOLVideoEvent
  • IOLVideoEventType.Play
  • IOLVideoEventType.Pause
  • IOLVideoEventType.Stop
  • IOLVideoEventType.Next
  • IOLVideoEventType.Previous
  • IOLVideoEventType.Replay
  • IOLVideoEventType.SeekBack
  • IOLVideoEventType.SeekForward
• IOLViewEvent
  • IOLViewEventType.Appeared
  • IOLViewEventType.Refreshed
  • IOLViewEventType.Disappeared

More details about the measurable events and the associated states are described here [here] (defaults_to_call.md).

Examples:

IOLViewEvent / IOLViewEventType.Appeared

1
2
3
4
5
6
7

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    val event = IOLViewEvent(type = IOLViewEvent.IOLViewEventType.Appeared,
                             category = "MainScreen")
    App.IOMB_SESSION.logEvent(event)
}

IOLViewEvent / IOLViewEventTypeRefreshed

1
2
3
4
5
6
7
8

override fun onResume() {
    super.onResume()

    val event = IOLViewEvent(type = IOLViewEvent.IOLViewEventType.Refreshed,
                             category = "MainScreen",
                             comment = "Content refreshed")
    App.IOMB_SESSION.logEvent(event)
}

IOLAudioEvent / IOLAudioEventTypePlay

1
2
3
4
5
6
7
8

override fun onResume() {
    super.onResume()

    val event = IOLAudioEvent(type = IOLAudioEvent.IOLAudioEventType.Play,
                              category = "Audio",
                              comment = "Audio Playback")
    App.IOMB_SESSION.logEvent(event)
}

End session¶

The active session of the IOMb lib can be terminated explicitly. This allows e.g. the realization of an Opt-out during the app runtime. Any data collected up to that point will no longer be sent.

NOTE: Use only when opt-out by the user!

1

IOMB.delete(Measurement.Type.IOMB)