Conviva Rust Sensor Integration

Download the Rust SDK library from the RUST SDK downloads page.

Install the Conviva library and import these modules:

use convivasdk::common::types::*;
use convivasdk::platform_if::*;
use convivasdk::player_if::CISPlayerIf;
use convivasdk::client::*;
/// Add below module only if Experiance Insights is required
use convivasdk::video_session::CISVideoSession;
/// Add below module only if Ad Insights is required
use convivasdk::ad_session::CISAdSession;

Initialize the Conviva Rust Client by calling get_conviva_client() by providing customer_key, platform_interface, and settings parameters.

pub fn get_conviva_client(
    customer_key: String,
    platform_if: &'static CISPlatformIf,
    settings: Option<CISSettings>
) -> Result<CISClient, CISError> {}

• customer_key: String to identify specific customer account. Different keys shall be used for development / debug versus production environment. Find your keys on the account info page in Pulse;

• platform_interface: Your implementation of CISPlatformIf for your device.

• settings: [Optional] Custom settings of type CISSettings for the library. The allowed parameters are:

fn configure_settings() -> CISSettings {
    /// Instantiate settings interface
    let mut settings = CISSettings::new();
    // Configure settings
    settings.gateway_url = Some(GW_URL.to_string());
    return settings;
}

Expected Errors Due to Dual Stack IPv4/v6 Network Support

When the Conviva sensor is initialized with production settings, the SDK sends a single request to the endpoints below:

• [customer_key].ipv4.cws.conviva.com for IPv4 only

• [customer_key].ipv6.cws.conviva.com for IPv6 only

Sending both requests enables correlation of IPv4 and IPv6 addresses in dual-stack networks. If only IPv4 or IPv6 addressing is used (single-stack networking), it is expected that one request will fail. All the following requests will be sent to the endpoint below, which supports both IPv4 and IPv6:

• [customer_key].cws.conviva.com

The CISPlatformIf structure allows the client to implement the platform dependent functions for the Conviva library, such as Http_Post, timer, and storage. For example, to send the HTTP Posts, implement the send_http_post_request() method as shown in this example:

async fn send_http_post_request(
    &self,
    url: &str,
    content_type: &str,
    data: &str,
    timeout: u32
) -> Result<CISHttpResponse,()> {
    let mut f = File::options().append(true).open("./hbRust.json").expect("Unable to open");
    let client = reqwest::Client::new();
    let response: Result<CISHttpResponse, CISError> = client
        .post(url)
        .header("Accept", "application/json")
        .header("Content-Type", "application/json")
        .header("User-Agent", "rust-agent/1.0")
        .body(data.to_string())
        .send().await
        .unwrap()
        .text().await
        .and_then(
            |res| -> Result<CISHttpResponse, _> {
                println!("Response {}", res);
                Ok(CISHttpResponse { response: res, http_response_code: 200 })
            }
        )
        .or_else(
            |err| -> Result<_, CISError> {
                Err(CISError { status_code: CISErrorCode::Failed, message: "".to_string() })
            }
        );
    response
}

A complete example that runs on a Linux machine is included in the SDK inside test or sample-app folder.

While initializing Rust SDK through get_conviva_client(), the application provides all the platform metadata in CISPlatformMetaData structure while passing the CISPlatformIf instance. Here’s an example that demonstrates the get_platform_metadata() call back implementation:

fn platform_meta_data() -> CISPlatformMetaData {
    let platform_metadata = CISPlatformMetaData {
		device_brand: "Playstation".to_string(),
		device_manufacturer: "Sony".to_string(),
		device_model: "PS4 Pro".to_string(),
		device_type: CISDeviceType::Desktop,
		device_version: "A136".to_string(),
		framework_name: "mediax".to_string(),
		framework_version: "WASM:2.5.6;PLUGIN:4.2.13".to_string(),
		operating_system_name: "Sony_System_Software".to_string(),
		operating_system_version: "2.0.0+.09-00.00.00.0.1".to_string(),
		screen_height: Some(1080),
		screen_width: Some(1920),
		screen_scale_factor: Some(2.0),
		schema: "sdk.rust.1".to_string(),
		category: "LNX".to_string(),
    };
    return platform_metadata;
}

static PLATFORM_INSTANCE: OnceCell<CISPlatformIf> = OnceCell::new();
fn get_platform_if() -> CISPlatformIf {
    let storage_if = app_platform_if::AppStorageIf::new();
    // Instantiate http interface
    let http_if = app_platform_if::AppHttpIf::new();
    //let platform_metadata: CISPlatformMetaData = platform_meta_data();
    let platform_metadata: CISPlatformMetaData = CISPlatformMetaData::new();
    let utils = UtilsIf {};
    let async_task_if = app_platform_if::AppAsyncTaskIf::new();

    // Configure platform interface
    CISPlatformIf::new(platform_metadata, http_if, storage_if, utils,async_task_if)
}


// Instantiate settings interface
let mut settings = configure_settings();
let _ = PLATFORM_INSTANCE.set(get_platform_if());
let mut conviva_data = ConvivaData::new();
// Create conviva client by passing customer key,platform interface and settings
let conviva_client_result = get_conviva_client(
    CUSTOMER_KEY.to_string(),
    PLATFORM_INSTANCE.get().unwrap(),
    Some(settings)
);

Implement pre-defined and custom tags for video by setting the properties of the CISContentInfo object.

An example to illustrate pre-defined and custom metadata implementation for video:

fn create_metadata() -> CISContentInfo {
    /// Configure metadata
    let mut content_info = CISContentInfo::new();
    content_info.asset_name = Some("Guardians of the Galaxy".to_string());
    content_info.default_bitrate = Some(5555);
    content_info.default_average_bitrate = Some(3333);
    content_info.viewer_id = Some("9ea10d4c-f458-4b90-b5f7-4e01f06bfed5".to_string());
    content_info.player_name = Some("DemoPlayerName++".to_string());
    content_info.stream_url = Some("http://Stream_Url.m3u8".to_string());
    content_info.is_live = Some(false);
    content_info.duration = Some(100);
    content_info.default_resource = Some("DEFAULT_RC_new".to_string());
    let mut tags: HashMap<String, CISGenericValueType> = HashMap::new();
    tags.insert("tag1".to_string(), CISGenericValueType::CisStringValue("test".to_string()));
    content_info.tags = Some(tags);
    return content_info;
}

Implement pre-defined and custom tags for ad content by setting the properties of the CISContentInfo object.

Refer to the below example illustrating pre-defined and custom metadata for ads:

//Create ad_info
fn create_ad_server_side_metadata()-> CISContentInfo {
	let  mut  ad_info = CISContentInfo::new();
	ad_info.asset_name = Some("Server_Side_Asset_Name".to_string());
	ad_info.duration = Some(30);
	ad_info.default_resource = Some("adDEFAULT_RC_new".to_string());
	ad_info.stream_url = Some(("adurl.conviva.com").to_string());
	let  mut  tags:  HashMap<String, CISGenericValueType> = HashMap::new();
	tags.insert("tag1ad".to_string(),CISGenericValueType::CisStringValue("test".to_string()));
	ad_info.tags  =  Some(tags);
	return  ad_info;
}

pub fn report_ad_break_started(
    &mut self,
    ad_player_type: CISAdPlayerType,
    ad_technology: CISAdTechnology,
    pod_info: Option<CISPodInfo>
) -> Result<(), CISError>;

• ad_player_type: informs Conviva sensor which player is used to play the ads - the same as main video content or separate instance.

• ad_technology: specifies type of the ad (server side / client side);

• pod_info: Ad pod info like pod position, pod index, and pod duration.

Sample code to illustrate the reporting of client-side and server-side ads: Client-side Ads

video_session.report_ad_break_started(
    CISAdPlayerType::Content,
    CISAdTechnology::ClientSide,
    Some(pod_info_preroll)
);

video_session.report_ad_break_started(
    CISAdPlayerType::Content,
    CISAdTechnology::ServerSide,
    None
);

video_session.report_ad_break_ended();

Use the following method to create Conviva monitoring session upon user playback request, along with metadata (content, workflow, audience, and other relevant metadata):

pub fn create_session(
    &mut self,
    content_info: CISContentInfo
) -> Result<CISVideoSession, CISError>;

• content_info: Metadata associated with the content to be monitored.

• Returns a reference to CISVideoSession on success.

Sample code to illustrate video session creation:

// Configure metadata
let  content_info  =  create_metadata();
// Create video session
let  video_session_result  =  conviva_client.create_session(content_info);

IMPORTANT: It's critical to make this API call correctly to monitor video experience - monitoring session created from this moment, and key metrics are captured based on this event. For example, if this call done late (say, when video starts rather than user clicks 'play'), the Video Startup Time will be under-reported, Video Start Failures will be missed, etc.

Please note that each video should be monitored separately - call this method for each new video played.

IMPORTANT: If some of the content metadata tags aren't available at start, they can be set later or amended by calling update_content_info() API. To accurately attribute metadata to the video asset, it's required to set the content metadata before the player reports "play" for the first time,

Refer to the below table to know when to invoke the corresponding API calls:

Report the end of playback:

cleanup();