Permutive_iOS v1.4.0 Documentation

Protocol Media​Tracker​Protocol 

@objc(PermutiveMediaTrackerProtocol)
public protocol MediaTrackerProtocol: AdTargetable

A protocol defining the interface of a Video Tracker component.

The Video Tracker component is responsible for tracking interaction with video content. Video engagement is measured by the duration played and the end point reached. A trackEvent function is supplied to allow tracking of any event through the MediaTrackerProtocol instance. This is recommended to improve segmentation data.

The VideoTracker will start to time the engagement if paused or yet to be started on calling play. Video tracking can be paused and resumed through play once started and before stopping.

Custom events will only be tracked once a MediaTrackerProtocol instance has been started and before it has been stopped.

VideoTracker Usage:

  • Initialise:

   var videoTracker: MediaTrackerProtocol
   do {
       let properties = EventProperties(["name": "value"])
       let videoContext = Context(title: "<title>", url: <url>)
       videoTracker = try Permutive.shared.createVideoTracker(duration: asset.duration, properties: properties, context: videoContext)
   } catch {
       // Handle error
   }

  • Begin or resume playing or scrub to new position with supplied properties:

   do {
       let position: TimeInterval = 0
       try videoTracker.play(position: position, properties: properties)
   } catch {
       // Handle error
   }

  • Begin or resume playing or scrub to new position using previous properties value, if any:

   do {
       let position: TimeInterval = 0
       try videoTracker.play(position: position)
   } catch {
       // Handle error
   }

  • Track a custom event:

    do {
        try videoTracker.trackEvent(name: "CTAPressed",
                                    properties: EventProperties(["name": "value"]))
    } catch {
        // Handle error
    }

  • Update percentage of view seen

   videoTracker.updateViewed(percentage: 0.5)
MediaTrackerProtocol MediaTrackerProtocol AdTargetable AdTargetable MediaTrackerProtocol->AdTargetable MediaTracker MediaTracker MediaTracker->MediaTrackerProtocol

Conforms To

AdTargetable

Requirements

play(position:​) 

func play(position: TimeInterval)

Starts or updates the MediaTracker instance and begins and any engagement timer, if the tracker was not previously active. Play called after stop will have no effect. Scrubbing can be achieved by calling play with a different position. Calling start will immediately initiate the engagement timer.

Parameters

position Time​Interval

The position at which play should begin. Use TimeInterval.infinity for live streaming.

play() 

func play()

Convenience play method matching play(position:) in effect but uses existing position.

pause() 

func pause()

Will pause the engagement timer, can be used if the app go in background, or at any other relevant time.

Pausing before play or after stop has no effect.

stop() 

func stop()

Will stop the engagement timer, can be used when a user transition to another page, or at any other relevant time. The final engagement time will be send to the engine, with the original EventProperties passed in parameter on start.

set(duration:​) 

func set(duration: TimeInterval)

If the video source duration is unknown at the time of creation, use this to set the media duration once known.

Will do nothing once the Media Tracker has been stopped.

  • Parameter

    • duration: The duration of the media.

track(event:​properties:​) 

func track(event: String, properties: EventProperties?) throws

This method tracks an event for this page with the Context supplied on creation of the VideoTracker. Tracking an event may be performed before starting the VideoTracker, however tracking an event after stopping in not permissable and will throw an exception.

Parameters

event String

The name of the page event to track.
properties Event​Properties?

The optional properties of the page event.