Skip to content

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 IOLib iOS described in the following must be called on the Default Session object. The IOMbLib 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 IOLib 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
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 IOLib.

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 IOLib 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.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.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.logEvent(event)
        // Other page code ...
    }
}

Terminate session

func terminateSession()

The active session of the IOLib 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.

note

Use only when opt-out is done by the user!

1
2
3
4
5
6
class ViewController: UIViewController {

    func disableIOMBSession() {
        IOMBSession.defaultSession.terminateSession()
    }
}
note

If the measurement is to be continued, the IOLib session must be restarted! The procedure is described under Start a session.

Integration of Opt-out function

An Opt-out function must be made available to the users of an app. The implementation is the responsibility of the developer of the respective app and should result in the IOLib either not being initialized at all or the current session being explicitly terminated when activated by the user. The procedure is described under End session.

After the feature is included, users of the app can enable and disable the Opt-out. Provided an Opt-out is enabled, no measurement data will be collected.

note

If a running session is explicitly terminated, then all measurement data collected up to that point but not yet sent will be discarded.

If the Opt-out is revised, then the IOLib should be started again. The procedure is described under Start a session.


Last update: April 7, 2022