The following page contains instructions on how to integrate using iOS/tvOS SDK for a few advanced use cases, such as reporting live program and playlist changes, fatal errors, etc. After completing the initial stream sensor integration, use these instructions as an add-on to achieve specific goals.
Switching Between Landscape and Portrait Modes
If the user switches screen orientation during video playback, the video monitoring session should continue uninterrupted. The session is cleaned up only when the playback ends or the user explicitly closes the player.
Switching Between Full-screen and Picture-in-Picture (PiP) Modes
If a user switches between Full-screen and Picture-in-Picture (PiP) modes, the video monitoring session should continue uninterrupted. The session should be cleaned up when playback ends or the user explicitly closes the player.
Handling Casting
Casting must be treated as a playback context change. If the Chromecast/receiver integrates Conviva, create and maintain the monitoring session on the receiver. When casting starts during sender playback, terminate the sender session at handoff and create a new receiver session for Chromecast playback.
Report Live, Live Linear, or FAST Program Changes
Report program changes during live, live linear, or FAST streaming
Users may switch from one program to another at the program boundary either during live or live linear streaming. To report these changes, use the videoAnalytics.setContentInfo(newContentInfo) API in Swift or videoAnalytics setContentInfo:newContentInfo API in Objective C, and update the asset name that has changed at the program boundary.
The following is the sample code:
// update ASSET_NAME and any other metadata that has changed.
var newContentInfo = [String: Any]()
newContentInfo[CIS_SSDK_METADATA_ASSET_NAME] = "Asset name of the next program"
videoAnalytics.setContentInfo(newContentInfo)
// update ASSET_NAME and any other metadata that has changed.
NSMutableDictionary *newContentInfo = [[NSMutableDictionary alloc] init];
[newContentInfo setValue:@"Asset name of the next program" forKey:CIS_SSDK_METADATA_ASSET_NAME];
[videoAnalytics setContentInfo:newContentInfo];
Report Playlist Changes
Report video changes in playlist
Users may switch from one playlist item to another during streaming. To report these changes, close the previous session and open a new session. Then, set the metadata using the videoAnalytics.setContentInfo(newContentInfo) API in Swift or videoAnalytics setContentInfo:newContentInfo API in Objective C.
The following is the sample code:
// close the previous session
...
// open a new session with new metadata
...
var newContentInfo = [String: Any]()
newContentInfo[CIS_SSDK_METADATA_ASSET_NAME] = "Next playlist item"
videoAnalytics.setContentInfo(newContentInfo)
// close the previous session
...
// open a new session with new metadata
...
NSMutableDictionary *newContentInfo = [[NSMutableDictionary alloc] init];
[newContentInfo setValue:@"Next playlist item" forKey:CIS_SSDK_METADATA_ASSET_NAME];
[videoAnalytics setContentInfo:newContentInfo];
Report Errors
Playback does not recover from error and is reported once only
Playback encounters a fatal error from which it does not recover. Use the videoAnalytics.reportPlaybackFailed(errorMessage, contentInfo: contentInfo) API in Swift or [videoAnalytics reportPlaybackFailed:errorMessage contentInfo:contentInfo] API in Objective C to report this to Conviva, so that Conviva can close the monitoring session.
The following is the sample code:
videoAnalytics.reportPlaybackFailed(errorMessage, contentInfo: contentInfo)
[videoAnalytics reportPlaybackFailed:errorMessage contentInfo:contentInfo];
Retry - Playback does not recover from error and fatal errors are reported multiple times
Playback encounters an initial fatal error from which it does not recover. However, an application or player timeout triggers a retry behavior. In such a use case, invoke the videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: ErrorSeverity.ERROR_FATAL) API in Swift or [videoAnalytics reportPlaybackError:errorMessage errorSeverity:ERROR_FATAL] API in Objective C to report each error to Conviva, so that Conviva can keep the session active until all retry attempts are exhausted. When no more retries are available from the application's perspective, the Conviva monitoring session is closed.
The following is the sample code:
// retry attempt 1, after first fatal error
videoAnalytics.reportPlaybackError(errorMessage_1, errorSeverity: ErrorSeverity.ERROR_FATAL)
// retry attempt 2, after second fatal error
videoAnalytics.reportPlaybackError(errorMessage_2, errorSeverity: ErrorSeverity.ERROR_FATAL)
// retry attempt 3, after 3rd fatal error
videoAnalytics.reportPlaybackError(errorMessage_3, errorSeverity: ErrorSeverity.ERROR_FATAL)
.
.
.
// retry attempt n, after nth fatal error and the app has no more retries
videoAnalytics.reportPlaybackError(errorMessage_n, errorSeverity: ErrorSeverity.ERROR_FATAL)
videoAnalytics.reportPlaybackEnded()
// retry attempt 1, after first fatal error
[videoAnalytics reportPlaybackError:errorMessage_1 errorSeverity:ERROR_FATAL];
// retry attempt 2, after second fatal error
[videoAnalytics reportPlaybackError:errorMessage_2 errorSeverity:ERROR_FATAL];
// retry attempt 3, after 3rd fatal error
[videoAnalytics reportPlaybackError:errorMessage_3 errorSeverity:ERROR_FATAL];
.
.
.
// retry attempt n, after nth fatal error and the app has no more retries
[videoAnalytics reportPlaybackError:errorMessage_n errorSeverity:ERROR_FATAL];
[videoAnalytics reportPlaybackEnded];
Playback recovers from a fatal error by switching to a different asset URL
Playback has encountered an error and on retrying with a different asset url, it recovered during the same playback session. In such cases, use the videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: ErrorSeverity.ERROR_FATAL) API in Swift or [videoAnalytics reportPlaybackError:errorMessage errorSeverity:ERROR_FATAL] API in Objective C to report the error and videoAnalytics.setContentInfo(newContentInfo) API in Swift or [videoAnalytics setContentInfo:newContentInfo] API in Objective C to update the stream URL once the playback has recovered.
The following is the sample code:
videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: ErrorSeverity.ERROR_FATAL)
..
var newContentInfo = [String: Any]()
newContentInfo[CIS_SSDK_METADATA_STREAM_URL] = "UPDATED_STREAM_URL"
videoAnalytics.setContentInfo(newContentInfo)
[videoAnalytics reportPlaybackError:errorMessage errorSeverity:ERROR_FATAL];
..
NSMutableDictionary *newContentInfo = [[NSMutableDictionary alloc] init];
[newContentInfo setValue:@"UPDATED_STREAM_URL" forKey:CIS_SSDK_METADATA_STREAM_URL];
[videoAnalytics setContentInfo:newContentInfo];
Playback recovery in multi CDN scenario
Playback has encountered an error and on retrying with a different CDN, it recovered during the same playback session. In such cases, use the videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: ErrorSeverity.ERROR_FATAL) API in Swift or [videoAnalytics reportPlaybackError:errorMessage errorSeverity:ERROR_FATAL] API in Objective C to report the error and videoAnalytics.setContentInfo(newContentInfo) API in Swift or [videoAnalytics setContentInfo:newContentInfo] API in Objective C to update the stream URL corresponding to the newer CDN once the playback has recovered.
The following is the sample code:
videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: ErrorSeverity.ERROR_FATAL)
..
var newContentInfo = [String: Any]()
newContentInfo[CIS_SSDK_METADATA_STREAM_URL] = "UPDATED_STREAM_URL"
videoAnalytics.setContentInfo(newContentInfo)
[videoAnalytics reportPlaybackError:errorMessage errorSeverity:ERROR_FATAL];
..
NSMutableDictionary *newContentInfo = [[NSMutableDictionary alloc] init];
[newContentInfo setValue:@"UPDATED_STREAM_URL" forKey:CIS_SSDK_METADATA_STREAM_URL];
[videoAnalytics setContentInfo:newContentInfo];
Playback is not impacted due to a warning error type
The player or application encountered an error that does not impact video playback. However, if you still want to report it, then ensure to report it as WARNING. Invoke the videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: ErrorSeverity.ERROR_WARNING) API in Swift or [videoAnalytics reportPlaybackError:errorMessage errorSeverity:ERROR_WARNING] API in Objective C to report the error severity as a warning.
The following is the sample code:
videoAnalytics.reportPlaybackError(errorMessage, errorSeverity: ErrorSeverity.ERROR_WARNING)
[videoAnalytics reportPlaybackError:errorMessage errorSeverity:ERROR_WARNING];
Optimize Monitoring During User Wait State
User Actions: User Dialogues
Conviva prefers to optimize certain portions of monitoring during user wait state, so that it does not inaccurately reflect in metrics like VST. For that, monitoring must be turned off when video playback request is halted due to user dialogues like:
pin popup
accepting strong language or violence
confirming age
startover or resume dialogue
watch party initiation
These user dialogues can be handled using the following APIs:
On user wait started:
videoAnalytics.reportPlaybackEvent(CISConstants.getEventsStringValue(Events.USER_WAIT_STARTED), withAttributes: nil)
[videoAnalytics reportPlaybackEvent:[CISConstants getEventsStringValue:USER_WAIT_STARTED] withAttributes:nil];
On user wait ended:
videoAnalytics.reportPlaybackEvent(CISConstants.getEventsStringValue(Events.USER_WAIT_ENDED), withAttributes: nil)
[videoAnalytics reportPlaybackEvent:[CISConstants getEventsStringValue:USER_WAIT_ENDED] withAttributes:nil];
User Actions: Backgrounding and Foregrounding
To handle backgrounding events (for example, pressing home or power off buttons), use:
analytics.reportAppBackgrounded()
[analytics reportAppBackgrounded];
To handle foregrounding events:
analytics.reportAppForegrounded()
[analytics reportAppForegrounded];