IOMb Library iOS Functions¶

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

Calling the Default Session¶

All functions of the IOMbLib iOS v1.1+ described in the following must be called on the Default Session object. The IOMbLib contains multiple measurement systems, therefore a SessionType has to be passed as parameter.

1

let session = IOMBSession.defaultSession(for: .iomb)

NOTE for IOMb Library Version 1.0.x

The IOMbLib v1.0.x contains only the IOMb measurement system, therefore no SessionType has to be passed as parameter.

1

let session = IOMBSession.defaultSession

Configuration of a session¶

NOTE: Before starting an IOMb session a valid configuration object must be created

Parameters:

• Site ID (mandatory).

  A unique identifier of the site of the respective app. The site ID is assigned uniquely 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

guard let url = URL(string: "https://data-ef4e2c0163.example.com") else { return }
let configuration = IOMBSessionConfiguration(offerIdentifier: "site ID", baseURL: url)

Start a session¶

NOTE: The IOMbLib must be started before the events are captured. The site ID of the app and a valid baseURL must be set correctly in the SessionConfiguration (see above).

Parameters:

• SessionConfiguration (mandatory).

  A SessionConfiguration object. For the IOMb measurement IOMBSessionConfiguration must be used!

Example:

1
2

v1.1.+: IOMBSession.defaultSession(for: .iomb).start(with: configuration)
v1.0.x: IOMBSession.defaultSession.start(with: configuration)

Logging an event¶

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

1

func logEvent(_ event: IOMBEvent)

To create an event, an initializer of the corresponding IOMBEvent subclass must be called. Up to three parameters can be passed, two of which are optional (ParameterDictionary is a Swift typealias for Dictionary<String, String>).

1
2
3
4

IOMBEvent(type: IOMBEventType,
          category: String?
          comment: String?,
          parameter: ParameterDictionary?)

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

Parameter:

• EventType (mandatory)

  The individual events can take 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 IOMBCustomEvent 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, nil shall be passed.

• Parameter (optional)

  A dictionary 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, if it is not defined, nil should be passed.

Available events¶

The IOMbLib provides the following event classes derived from "IOMBEvent" with their associated types:

• IOMBAdvertisementEvent.
  • IOMBAdvertisementEventTypeOpen
  • IOMBAdvertisementEventTypeClose
• IOMBAudioEvent
  • IOMBAudioEventTypePlay
  • IOMBAudioEventTypePause
  • IOMBAudioEventTypeStop
  • IOMBAudioEventTypeNext
  • IOMBAudioEventTypePrevious
  • IOMBAudioEventTypeReplay
  • IOMBAudioEventTypeSeekBack
  • IOMBAudioEventTypeSeekForward
• IOMBBackgroundTaskEvent
  • IOMBBackgroundTaskEventTypeStart
  • IOMBBackgroundTaskEventTypeEnd
• IOMBCustomEvent
  • type omitted
  • name instead (freely definable string, limited to 255 characters)
• IOMBDataEvent
  • IOMBDataEventTypeCancelled
  • IOMBDataEventTypeRefresh
  • IOMBDataEventTypeSucceeded
  • IOMBDataEventTypeFailed
• IOMBDeviceOrientationEvent
  • type omitted (IOMBDeviceOrientationEventTypeOrientationChanged)
• IOMBDocumentEvent
  • IOMBDocumentEventTypeOpen
  • IOMBDocumentEventTypeEdit
  • IOMBDocumentEventTypeClose
• IOMBDownloadEvent
  • IOMBDownloadEventTypeCancelled
  • IOMBDownloadEventTypeStart
  • IOMBDownloadEventTypeSucceeded
  • IOMBDownloadEventTypeFailed
• IOMBGameEvent
  • IOMBGameEventTypeAction
  • IOMBGameEventTypeStarted
  • IOMBGameEventTypeFinished
  • IOMBGameEventTypeWon
  • IOMBGameEventTypeLost
  • IOMBGameEventTypeNewHighscore
  • IOMBGameEventTypeNewAchievement
• IOMBGestureEvent
  • type not applicable (IOMBGestureEventTypeShake)
• IOMBHardwareButtonEvent
  • type not applicable (IOMBHardwareButtonEventTypePushed)
• IOMBIAPEvent
  • IOMBIAPEventTypeStarted
  • IOMBIAPEventTypeFinished
  • IOMBIAPEventTypeCancelled
• IOMBLoginEvent
  • IOMBLoginEventTypeSucceeded
  • IOMBLoginEventTypeFailed
  • IOMBLoginEventTypeLogout
• IOMBOpenAppEvent
  • IOMBOpenAppEventTypeMaps
  • IOMBOpenAppEventTypeOther
• IOMBPushEvent
  • type omitted (IOMBPushEventTypeReceived)
• IOMBUploadEvent
  • IOMBUploadEventTypeCancelled
  • IOMBUploadEventTypeStart
  • IOMBUploadEventTypeSucceeded
  • IOMBUploadEventTypeFailed
• IOMBVideoEvent
  • IOMBVideoEventTypePlay
  • IOMBVideoEventTypePause
  • IOMBVideoEventTypeStop
  • IOMBVideoEventTypeNext
  • IOMBVideoEventTypePrevious
  • IOMBVideoEventTypeReplay
  • IOMBVideoEventTypeSeekBack
  • IOMBVideoEventTypeSeekForward
• IOMBViewEvent
  • IOMBViewEventTypeAppeared
  • IOMBViewEventTypeRefreshed
  • IOMBViewEventTypeDisappeared

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

Examples*

• IOMBViewEvent / IOMBViewEventTypeAppeared

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

class ViewController: UIViewController {

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        let event = IOMBViewEvent(type: .appeared,
                                  category: "Home",
                                  comment: nil)
        IOMBSession.defaultSession(for: .iomb).logEvent(event)
        // Other page code ...
   }
}

• IOMBViewEvent / IOMBViewEventTypeRefreshed

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

class ViewController: UIViewController {

    @IBAction func refresh(sender: AnyObject) {
        let event = IOMBViewEvent(type: .refreshed,
                                  category: "Home",
                                  comment: "Content refreshed")
        IOMBSession.defaultSession(for: .iomb).logEvent(event)
        // Other page code ...
    }
}

• IOMBAudioEvent / IOMBAudioEventTypePlay

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

class ViewController: UIViewController {

    @IBAction func refresh(sender: AnyObject) {
        let event = IOMBAudioEvent(type: .play,
                                   category: "Audio"
                                   comment: "Audio playback")
        IOMBSession.defaultSession(for: .iomb).logEvent(event)
        // Other page code ...
    }
}

Terminate session¶

func terminateSession()

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

1
2
3
4
5
6

class ViewController: UIViewController {

    func disableIOMBSession() {
        IOMBSession.defaultSession(for: .iomb).terminateSession()
    }
}