API Reference

AVPlayer (iOS)

Gumlet Insights integration with AVPlayer for iOS native applications.

This Insights SDK enables you to get useful data about video usage in your apps. AVPlayer is an iOS native feature to manage the playback. AVPlayer are two approaches AVPlayerLayer and AVPlayerViewController.

Step 1: Add the SDK to the Project

Gumlet Insights is available through CocoaPods and Swift package Manager.

Install Gumlet Insights SDK with Cocoapods

  1. Create Podfile or modify Podfile to use SDK(frameworks) by using use_frameworks!
  2. Add the pod inside the Podfile
# platform :ios, '13.0'
use_frameworks!

target 'InsightsDemoApp' do

  # Pods for InsightsDemoApp
	pod 'GumletInsightsSDKAVPlayer', '~>1.0'
    
end
  1. Run pod repo update to add the newly added source and run Pod install to install it.
  2. import SDK on your file
 import GumletInsightsSDKAVPlayer

Install Gumlet Insights SDK with Swift Package Manager(SwiftPM)

  1. In Xcode click “File” > ”Swift Packages” > “Add Package Dependency…”
  2. The package repository URL is - https://github.com/gumlet/gumlet-insights-sdk-avplayer.git
  3. Click Next
  4. Select default Branch of the package main and click Next
  5. Xcode downloads the Gumlet Insights package to the your app target.
  6. import SDK on your file
 import GumletInsightsSDKAVPlayer
  1. Click Finish.

Step 2: Setup the Gumlet Insights to the your app

Get Property ID from Gumlet Dashboard.

With AVPlayerViewController use initAVPlayerViewController method and if you are using AVPlayerLayer , use initAVPlayerLayer method instead.

 let playerVC = AVPlayerViewController()

 let gumletConfig = GumletInsightsConfig()
 gumletConfig.proprtyId = "Your Property ID"

 GumletInsightsSDK.initAVPlayerViewController(playerVC, config:gumletConfig)

👍

Done

Once you integrate with these steps, you should start seeing data on your customised dashboard.

How to?

Add custom data

You can send first party user data to our dashboard via the SDK. While building the configuration to initialise the SDK object you can pass these parameters.

Gumlet allows metadata for user, player and video via GumletInsightsCustomUserData, GumletInsightsCustomPlayerData and GumletInsightsCustomVideoData

 let gumletConfig = GumletInsightsConfig()
 gumletConfig.proprtyId = "Your Property ID"
 
 let userData = GumletInsightsCustomUserData()
 userData.userId ="123"
 userData.userName ="Océane Bourgeois"
 userData.userEmail = "[email protected]"
 userData.userPhone = "(840)-295-4133"
 userData.userProfileImage = "https://assets.gumlet.io/assets/gumlet-logo-white-font.png?w=240&format=auto"
 userData.userAddressLine1 = "8774, Rue de la Mairie"
 userData.userAddressLine2 = ""
 userData.userCity = "Reims"
 userData.userState = "Landes"
 userData.userCountry = "France"
 userData.userZipcode = "83894"

 let customVideoData = GumletInsightsCustomVideoData()
 customVideoData.customVideotitle = "Pilot";
 customVideoData.customVideoId = "HIMYMSeason1Episode1"
 customVideoData.customVideoProducer = "Ece Tekelioglu"
 customVideoData.customContentType = "episode"
 customVideoData.customVideoDurationMillis = 2600000  // 43 minutes 20 seconds
 customVideoData.customVideoSeries = "HIMYMSeason1"
 customVideoData.customVideoVariantName = ""
 customVideoData.customVideoVariant = ""
 customVideoData.customEncodingVariant = "test1"
 customVideoData.customVideoLanguage = "English"

 let playerData = GumletInsightsCustomPlayerData()
 playerData.GumletPlayerName = "Trailer"
 playerData.GumletPlayerIntegrationVersion = "v1.1"
 playerData.gumletPageType = "Homepage"

 GumletInsightsSDK.initAVPlayerViewController(playerVC, userData: userData, customPlayerData: playerData, customVideoData: customVideoData, config: gumletConfig)

Change the essential user details being sent to the Gumlet Dashboard.

If the user decides to login after the Gumlet SDK was attached to the player then you can use the following function to update the data being sent to the Gumlet backend.

Use the updateData() function available in the SDK

let userData = GumletInsightsCustomUserData()
userData.userId ="123"
userData.userName ="Christelle Robert"
userData.userEmail = "[email protected]"

GumletInsightsSDK.updateData(playerVC, userData: userData)

Change the video title that is being played in the player.

If your app supports multiple videos in the same player after it is initialised then you need to tell our SDK to track the new video details after the player finishes playing a video and is about to start the new video.

Use the updateData() function available in the SDK

let customVideoData = GumletInsightsCustomVideoData()
customVideoData.customVideotitle ="Episode2"

GumletInsightsSDK.updateData(playerVC, customVideoData: customVideoData)

API Documentation

GumletInsightsConfig()

This class is used to create a configuration object which is mandatory to initialise Gumlet Insights SDK. It has the unique property id for your project which can be generated from the dashboard

let gumletConfig = GumletInsightsConfig()
gumletConfig.proprtyId = "Your Property ID"

initAVPlayerViewController(playerVC, config: gumletConfig, userData: userData, customPlayerData: playerData, customVideoData: customVideoData)

Use this method to initialise Gumlet SDK to start monitoring events on the given AVPlayerViewController. The function expects mandatory configuration object and the AVPlayerViewController object to hook on.
This is the minimum you need to do to get started.

let playerVC = AVPlayerViewController()

let gumletConfig = GumletInsightsConfig()
gumletConfig.proprtyId = "Your Property ID"

GumletInsightsSDK.initAVPlayerViewController(playerVC, config:gumletConfig)

There is an option to pass different custom data viz. custom user data, custom player data and custom video data.

let playerVC = AVPlayerViewController()

let gumletConfig = GumletInsightsConfig()
gumletConfig.proprtyId = "Your Property ID"

let userData = GumletInsightsCustomUserData()
userData.userId ="123"
userData.userName ="Océane Bourgeois"
userData.userEmail = "[email protected]"
userData.userPhone = "(840)-295-4133"
userData.userProfileImage = "https://assets.gumlet.io/assets/gumlet-logo-white-font.png?w=240&format=auto"
userData.userAddressLine1 = "8774, Rue de la Mairie"
userData.userAddressLine2 = ""
userData.userCity = "Reims"
userData.userState = "Landes"
userData.userCountry = "France"
userData.userZipcode = "83894"

let customVideoData = GumletInsightsCustomVideoData()
customVideoData.customVideotitle = "Pilot";
customVideoData.customVideoId = "HIMYMSeason1Episode1"
customVideoData.customVideoProducer = "Ece Tekelioglu"
customVideoData.customContentType = "episode"
customVideoData.customVideoDurationMillis = 2600000  // 43 minutes 20 seconds
customVideoData.customVideoSeries = "HIMYMSeason1"
customVideoData.customVideoVariantName = ""
customVideoData.customVideoVariant = ""
customVideoData.customEncodingVariant = "test1"
customVideoData.customVideoLanguage = "English"

let playerData = GumletInsightsCustomPlayerData()
playerData.GumletPlayerName = "Trailer"
playerData.GumletPlayerIntegrationVersion = "v1.1"
playerData.gumletPageType = "Homepage"

GumletInsightsSDK.initAVPlayerViewController(playerVC, config:gumletConfig, userData: userData, customPlayerData: playerData, customVideoData: customVideoData)

GumletInsightsCustomUserData()

This class is used to create a configuration object which is used to pass user data to the dashboard via the Gumlet Insights SDK. The complete list of custom user parameters is available here

let userData = GumletInsightsCustomUserData()
userData.userId ="123"
userData.userName ="Océane Bourgeois"
userData.userEmail = "[email protected]"
userData.userPhone = "(840)-295-4133"
userData.userProfileImage = "https://assets.gumlet.io/assets/gumlet-logo-white-font.png?w=240&format=auto"
userData.userAddressLine1 = "8774, Rue de la Mairie"
userData.userAddressLine2 = ""
userData.userCity = "Reims"
userData.userState = "Landes"
userData.userCountry = "France"
userData.userZipcode = "83894"

GumletInsightsCustomVideoData()

This class is used to create a configuration object which is used to pass video data to the dashboard via the Gumlet Insights SDK. The complete list of custom video data parameters is available here

let customVideoData = GumletInsightsCustomVideoData()
customVideoData.customVideotitle = "Pilot";
customVideoData.customVideoId = "HIMYMSeason1Episode1"
customVideoData.customVideoProducer = "Ece Tekelioglu"
customVideoData.customContentType = "episode"
customVideoData.customVideoDurationMillis = 2600000  // 43 minutes 20 seconds
customVideoData.customVideoSeries = "HIMYMSeason1"
customVideoData.customVideoVariantName = ""
customVideoData.customVideoVariant = ""
customVideoData.customEncodingVariant = "test1"
customVideoData.customVideoLanguage = "English"

GumletInsightsCustomPlayerData()

This class is used to create a configuration object which is used to pass custom player data to the dashboard via the Gumlet Insights SDK. The complete list of custom player data parameters is available here

let playerData = GumletInsightsCustomPlayerData()
playerData.GumletPlayerName = "Trailer"
playerData.GumletPlayerIntegrationVersion = "v1.1"
playerData.gumletPageType = "Homepage"

updateData(playerViewController:AVPlayerViewController, userData:GumletInsightsUserData? = nil, customData:GumletInsightsCustomData? = nil,customVideoData:GumletInsightsCustomVideoData? = nil,customPlayerData:GumletInsightsCustomPlayerData? = nil)

There is an option to update different custom data parameters while the SDK has already been initialised. Each type of data is mutually exclusive and non mandatory. 

let userData = GumletInsightsCustomUserData()
userData.userId ="123"
userData.userName ="Christelle Robert"
userData.userEmail = "[email protected]"
userData.userPhone = "(078)-380-95-96"
userData.userProfileImage = "https://assets.gumlet.io/assets/gumlet-logo-white-font.png?w=240&format=auto"
userData.userAddressLine1 = "8774, Rue de la Mairie"
userData.userAddressLine2 = ""
userData.userCity = "Reims"
userData.userState = "Landes"
userData.userCountry = "France"
userData.userZipcode = "83894"

let customVideoData = GumletInsightsCustomVideoData()
customVideoData.customVideotitle = "episode";
customVideoData.customVideoId = "HIMYMSeason1Episode2"
customVideoData.customVideoProducer = "Ece Tekelioglu"
customVideoData.customContentType = "episode"
customVideoData.customVideoDurationMillis = "2405000"
customVideoData.customVideoSeries = "HIMYMSeason1"
customVideoData.customVideoVariantName = ""
customVideoData.customVideoVariant = ""
customVideoData.customEncodingVariant = "test1"
customVideoData.customVideoLanguage = "English"

GumletInsightsSDK.updateData(playerVC, config:gumletConfig, userData: userData, customVideoData: customVideoData)