Conviva C Sensor Integration

Conviva DPI Sensor Integration

#include <app_tracker.h>

snprintf(app_name, CCL_MAX_APP_NAME_LENGTH,"%s", "your_application_name_of_choice"); // mandatory field
snprintf(user_id, CCL_MAX_USER_ID_LENGTH,"%s", "logged_in_user_id_or_device_id");
cat_start_tracker(char* app_name, char* user_id);

char *user_id;
user_id = strdup("Enter your UserID Here");
cat_set_user_id(user_id);
free(user_id);

cat_app_info_t app_info;
// Set the optional parameters based on availability
app_info.app_load_start = 1752035360399; // Application Load Start time in seconds
app_info.app_load_end =  1752035360401; // Application Load End time in seconds
//Set the mandatory parameters after the tracker creation
sprintf(app_info.app_build, "%s", “1.2.0.1”);
sprintf(app_info.app_version, "%s", “v2.0”);

cat_set_application_info(&app_info);

// Set custom tags
ccl_dictionary_t *app_tags = ccl_dictionary_create();
ccl_dictionary_put (app_tags, “key1”, “value1”);
ccl_dictionary_put (app_tags, “key2”, “value2”);
cat_set_custom_tags(app_tags);

//Clear specific custom tags with keys
char *str = strdup("key1");

//clear the custom tag with key as “key1”
cat_clear_custom_tags(&str, 1); // list of keys and number of keys

//Clear all custom tags
cat_clear_all_custom_tags();

cat_track_app_install();

ccl_dictionary_put (dic, "key1", "value1");
ccl_dictionary_put (dic, "key2", "value2");
cat_send_custom_event ("CustomEvent1", dic);
ccl_dictionary_destroy (dic);

cat_screen_info_t screen;
memset(&screen, 0, sizeof(cat_screen_info_t));
screen.screen_name =strdup(“some name”);
screen.screen_type = strdup(“some_type”);
screen.load_start = 1752035360399;
screen.load_end = 1752035360401;
cat_track_screen_view (&screen);

cat_network_request_info_t nw_info;
memset(&nw_info, 0, sizeof(cat_network_request_info_t));
// target url – mandatory input
strcpy(nw_info.target_url, "test_url_1.com");
// method – mandatory input
strcpy(nw_info.method, "post");
// timestamps -> mandatory inputs, with valid timestamps in milliseconds
nw_info.request_timestamp = 1729745074745; 
nw_info.response_timestamp = 1729745074760;
// response status code – 0 will takes place if no valid value is set.
nw_info.response_code = 200;
cat_track_network_request(&nw_info);

// pause the tracker when needed.
cat_pause_tracker();
// resume the tracker when needed.
cat_resume_tracker();

cat_anr_info_t anr_info;
memset(&anr_info, 0, sizeof(cat_anr_info_t));
// Mandatory parameter
anr_info.anr_start = 1752035360401;
// Optional
anr_info.anr_reason = strdup("reason for ANR");

cat_track_anr(&anr_info);

cat_app_error_info_t app_error;
memset(&app_error,0, sizeof(cat_app_error_info_t));
app_error.error_lang = CAT_ERROR_LANG_C;
app_error.error_msg = strdup(“Error inside carousel access”);

cat_track_application_error(&app_error);

cat_stop_tracker();

Conviva Video Sensor Integration

Follow these instructions to complete the Conviva VSI Sensor integration on C players.

Prerequisites

Integration Summary

1. Install Conviva Library

• Install the library and add dependencies.

• Implement the platform interface.

• Implement device metadata as part of the platform interface.

• Initialize the library by calling ccl_init(CUSTOMER_KEY, platform_interface, settings) using your CUSTOMER_KEY.

2. Configure Metadata

• Implement the metadata by following the instructions to use the pre-defined keys, as well as custom metadata, if applicable.
• Report ad break start / end.
• Implement ad metadata, events and metric reporting (if applicable).

3. Report Events and Metadata

• Start monitoring session by calling ccl_session_create(content_info) method to report playback attempt request along with metadata (content, workflow, audience, and other relevant metadata). For the ads, start monitoring by calling ccl_ad_session_create(video_session, ad_content_info) for each ad in the ad break.
• Use the ccl_session_destroy(session) method to report the of end playback.
• Create an instance of ccl_player_t as a callback container object to report video related events.
• If your player has ads: create an instance of ccl_player_t for ads as a callback container object to report ad related events (if the ad player is different than video player).
• Implement start_monitoring() callback to retrieve the ccl_notifier_t object. Record the object for future use to report metrics.
• Implement metric reporting via ccl_player_t callbacks and ccl_notifier_t methods for both video and ads (if applicable).

4. Handle User Actions

• Handle user actions such as backgrounding, user dialogue, pin popup according to the specification.

• Report network_metrics.

5. Clean Up

• Call ccl_cleanup() to cleanup Conviva library and release memory / resources.

Test and Validate

1. After integration, perform a sanity check following the test cases in the Stream Sensor Sanity Test Plans spreadsheet. For the full validation test, use the test cases in the Stream Sensor Full Test Plans spreadsheet.

2. Use Touchstone in Pulse to perform self-validation and debugging of video sensor integration.

3. Done! Analyse your data in Pulse and improve your viewer experience - let's make video experience better!

API Reference Documentation

The Conviva C SDK includes Reference Documentation for video and DPI sensor APIs.

Sample Application

The sample application illustrating Conviva integration example can be found along with the library, in the same .zip file. Please refer to the next step below for details.

1. Install Conviva Library

Add Conviva Library and Implement Platform Interface

#include <ccl.h>

int ccl_init (const char * 	customer_key, const ccl_platform_t * platform_interface,
              const ccl_settings_t * settings)

/* platform must be available throughout the SDK life cycle: */
 
  ccl_platform_t platform = {
      save_data,
      load_data,
      http_post_request,
      console_log,
      epoch_time_ms,
      get_platform_metadata,
      create_timer,
      destroy_timer,
      rand,
      mutex_init,
      mutex_lock,
      mutex_unlock,
      mutex_destroy,
      rwlock_init,
      rwlock_rdlock,
      rwlock_wrlock,
      rwlock_unlock,
      rwlock_destroy,
      mem_alloc,
      mem_free
      NULL, // base64_encode - optional
      NULL, // generate_hash - optional
      generate_uuid,
      http_get_request
  };
 
  #ifdef DEBUG
const char *customer_key = "REPLACE_ME_BY_YOUR_TEST__CUSTOMER_KEY";
const char *gatewayUrl = "YOUR Touchstone Service URL";
#else
const char *customer_key = "REPLACE_ME_BY_YOUR_PRODUCTION_CUSTOMER_KEY>";
#endif
 
ccl_settings_t *settings = (ccl_settings_t *) mem_alloc(sizeof(ccl_settings_t));
ccl_settings_create(settings);
 
#ifdef DEBUG
strncpy(settings->gateway_url, gatewayUrl, CCL_MAX_URL_LENGTH);
settings->log_level = CCL_LOG_LEVEL_DEBUG;
#endif
ccl_init(customer_key, &platform, settings);
 
/* Settings can be destroyed immediately after the initialization: */
ccl_settings_destroy(settings);
free(settings);

uint64_t epoch_time_ms(void)
{
    struct timeval tv;
    gettimeofday(&tv, NULL);
    return (uint64_t) (tv.tv_sec * 1000LL + tv.tv_usec / 1000);
}

void* mem_alloc (size_t mem_size)
{
      if(mem_size > 0)
    return malloc(mem_size);
 
      return NULL;
}
void mem_free (void *memory)
{
      if(NULL != memory)
    free(memory);
}

/* Sample implementation of get_platform_metadata in application */
void get_platform_metadata (ccl_platform_metadata_t *metadata)
{
    metadata->device_type = CCL_DEVICE_TYPE_DESKTOP;
    metadata->device_category = CCL_DEVICE_CATEGORY_LNX;
    strncpy(metadata->device_brand, "Dell", CCL_MAX_PLATFORM_METADATA_LENGTH);
    strncpy(metadata->device_manufacturer, "Dell", CCL_MAX_PLATFORM_METADATA_LENGTH);
    strncpy(metadata->device_model, "x86_64", CCL_MAX_PLATFORM_METADATA_LENGTH);
    strncpy(metadata->device_version, "1.0", CCL_MAX_PLATFORM_METADATA_LENGTH);
    strncpy(metadata->framework_name, "gstreamer", CCL_MAX_PLATFORM_METADATA_LENGTH);
    strncpy(metadata->framework_version, "1.0", CCL_MAX_PLATFORM_METADATA_LENGTH);
    strncpy(metadata->operating_system_name, "Linux", CCL_MAX_PLATFORM_METADATA_LENGTH);
    strncpy(metadata->operating_system_version, "#31-Ubuntu SMP 2018", CCL_MAX_PLATFORM_METADATA_LENGTH);
    metadata->screen_height = 1080;
    metadata->screen_width  = 1920;
    metadata->screen_scale_factor = 1.0;
}

2. Configure Metadata

Metadata enables analysis of your data using different dimensions, for example, content, audience, device, workflow, player, and operating system.

Conviva categorizes metadata tags into three buckets (Predefined, Device, Custom).

// Create a ccl_content_info_t object and supply relevant metadata for the requested ads.
ccl_content_info_t *video_content_info = ccl_content_info_create();
// set the values for the fields defined in the ccl_content_info_t structure
video_content_info->asset_name = strdup("[channel_id] Live Channel Name");
 
// Create the dictionary for the custom tags:
video_content_info->tags = ccl_dictionary_create();
 
// Set the Conviva defined tag key/values to the dictionary:
ccl_dictionary_put(video_content_info->tags, "c3.cm.contentType", "Live-Linear");
 
// Set any custom tags as required:
ccl_dictionary_put(video_content_info->tags, "my_custom_tag_key", "my_custom_tag_value");
 
// Once the session is cleaned up, destroy the dictionary:
ccl_dictionary_destroy(video_content_info->tags);

/ Create a ccl_content_info_t object and supply relevant metadata for the requested ads.
ccl_content_info_t *ad_content_info = ccl_content_info_create();
// set the values for the fields defined in the ccl_content_info_t structure
ad_content_info->asset_name = strdup("My preroll ad title");
 
// Create the dictionary for the custom tags:
ad_content_info->tags = ccl_dictionary_create();
 
// Set the Conviva defined tag key/values to the dictionary:
ccl_dictionary_put(ad_content_info->tags, "c3.ad.id", "44556667445");
 
// Set any custom tags as required:
ccl_dictionary_put(ad_content_info->tags, "my_custom_tag_key", "my_custom_tag_value");
 
// Once the session is cleaned up, destroy the dictionary:
ccl_dictionary_destroy(ad_content_info->tags);

Pre-defined Metadata for Video and Ads

Conviva defines the constants or fixed string keys for commonly used metadata. These metadata keys provide critical information about video and ad content, versioning, workflow.

The below tags shall be added to both video and ad ccl_content_info_t objects:

Constants for Pre-defined Metadata for Video and Ads

IMPORTANT: To assign content category labels, such as Audio, Trailer, Tile Play, or Short Video, use the c3.cm.categoryType pre-defined content metadata constant.

Constants for Pre-defined Metadata for Video Only

These metadata tags shall be set via ccl_content_info_t* video_content_info->tags object for video session:

Constants for Pre-defined Metadata for Ads Only

Implement the pre-defined metadata specified in the table below.

These metadata tags shall be set via ccl_content_info_t* ad_content_info->tags object for ad session:

Device Metadata

The above section here prescribes how to implement platform metadata as a part of Platform Interface implementation. Device metadata is also used for inferring the device tags dimensions.

Custom Metadata

Refer to App Manager->Setup Metadata page for your account to find the custom tags which shall be implemented.

Set custom tags in a similar way for either video or ads, by using appropriate adAnalytics / videoAnalytics object and its corresponding method.

The API syntax can be found above in the corresponding sections for video and ads.

Update/Amend Metadata

To update or amend metadata for video or ads, use the method:

void ccl_session_update_content_info(ccl_session_t *session, const ccl_content_info_t *content_info)

• session shall specify the corresponding ccl_session_t reference of ad or video session;

• content_info is the object containing the updated or amended metadata, for ads or video correspondingly.

The device metadata can be immediately set when the values are available.

IMPORTANT: Please note that different Conviva products, such as Conviva VSI and Conviva Viewer Insights may have different logic with respect to handling updated values. Conviva recommends to update the metadata only when it is available and do not set any default values before the metadata is available.

Ad Events and Metadata

Report Ad Break

This step is required to accurately report Video Startup Time. The time taken by the ad break shall not be counted towards VST. Notify Conviva sensor of the ad break events using the following APIs described below.

int ccl_session_send_event(ccl_session_t *session, const char *name, ccl_dictionary_t *attributes)

int ccl_session_ad_start(ccl_session_t* session)

ccl_session_ad_start(video_session);

int ccl_session_ad_end(ccl_session_t* session)

ccl_session_ad_end(video_session);

int ccl_session_send_event(ccl_session_t *session, const char *name, ccl_dictionary_t *attributes)

The following steps are required when the video content contains pre-roll and mid-roll ads.

Handling Pre-Rolls

A common way to handle pre-roll ads is to preload the main content, pause it while the pre-roll ad plays, and then resume the main content after the pre-roll completes. Essentially, the ad plays while the main content is loaded. However, you don't want the play time for the ad to be counted as part of the Video Startup Time metric, nor do you want to be constantly polling the player while the ad runs. The solution is to notify the Conviva layer of the pre-roll's existence and its start and end events. To notify the PodStart and PodEnd, call the ccl_session_send_event() API . The ccl_session_player_attach() call is deferred, and the ccl_session_ad_start() API is called with required parameter. When the Pre-roll ad ends, call the ccl_session_ad_end API and attach ccl_player_t, as shown in the following code example:

// Report ad break start
ccl_dictionary_t *attr = ccl_dictionary_create();
ccl_dictionary_put(attr, "adType", "Server Side");
ccl_session_send_event(video_session, "Conviva.PodStart", attr);

// Report ad start upon video pause or request for the ads
ccl_session_ad_start(video_session);
// ... Ad play
// Report ad end once ad is played 
ccl_session_ad_end(video_session);

// Report ad break end
ccl_dictionary_put(attr, "adType", "Server Side");
ccl_session_send_event(video_session, "Conviva.PodEnd", attr);
// release the attribute
ccl_dictionary_destroy(attr);

// Attach content player to the video sesson to start monitoring
ccl_session_player_attach(video_session, ccl_player, player_data);

Handling Mid-Rolls

Ads played during the viewing of content are another case that needs to be handled correctly to maintain the accuracy of viewing metrics. For example, time spent viewing an ad should not be included in buffering ratio calculations. Likewise, your metrics would also be adversely affected by ending a session when an ad starts and starting a new session when it resumes.

The solution is detach the session when the main content stops and a mid-roll ad starts. To resume the session, you attach either the same player instance or a new player instance when the ad stops. Call ccl_session_ad_start() followed by session ccl_session_player_detach() when the main content stops and a Mid-roll ad starts. To resume session monitoring, attach the same ccl_player_t instance when the ad stops. To notify the PodStart and PodEnd, call the ccl_session_send_event() API.

The following API calls are needed to detach and re-attach the session to skip a mid-roll ad. These APIs are documented in the API Reference:

// As soon as the content is paused, call:
ccl_session_player_detach(ccl_session_t * video_session);

// Report ad break start
ccl_dictionary_t *attr = ccl_dictionary_create();
ccl_dictionary_put(attr, "adType", "Server Side");
ccl_session_send_event(video_session, "Conviva.PodStart", attr);

// Report ad start
ccl_session_ad_start(video_session);
// ... Ad play
// Report ad end once ad is played 
ccl_session_ad_end(video_session);

// Report ad break end
ccl_dictionary_put(attr, "adType", "Server Side");
ccl_session_send_event(video_session, "Conviva.PodEnd", attr);
// release the attribute
ccl_dictionary_destroy(attr);

// Attach content player to the video sesson to start monitoring
ccl_session_player_attach(video_session, ccl_player, player_data);

Implement Ad Metadata

Implement pre-defined common metadata and pre-defined ad metadata following the corresponding specifications.

Report Ad Metrics

The ad metrics and ad video events shall be implemented in a similar way to the main video content - using ccl_player_t callbacks or ccl_notifier_t interface. Refer to the above sections Init Interfaces and Report Metrics and events.

3. Report Events and Metadata

Manage Video Session

ccl_session_t* ccl_session_create(ccl_content_info_t * video_content_info)

/* Create a ccl_content_info_t object with video metadata */
  ccl_content_info_t *video_content_info = ccl_content_info_create();
  /* set the values for the fields defined in the ccl_content_info_t structure */
  /* Note that your application is responsible for memory allocation / release for the ccl_content_info_t fields */
  video_content_info->asset_name = strdup("[channel_id] Live Channel Name");
  // ... add the rest of metadata as prescribed by the below specification
 
  /* create a video session object with the content info */
  ccl_session_t *video_session = ccl_session_create(video_content_info);
 
  /* ccl_content_info object can be immediately destroyed, if no future metadata update required */
  free(video_content_info->asset_name);
  // .. release the memory for the rest of the fields
  ccl_content_info_destroy(video_content_info);
  video_content_info = 0;

ccl_session_destroy(video_session);

ccl_session_t* ccl_ad_session_create(ccl_session_t* video_session, ccl_content_info_t* ad_content_info)

/* Create a ccl_content_info_t object for ad metadata */
  ccl_content_info_t *ad_content_info = ccl_content_info_create();
  /* set the values for the fields defined in the ccl_content_info_t structure */
  /* Note that your application is responsible for memory allocation / release for the ccl_content_info_t fields */
  ad_content_info->asset_name = strdup("[ad_id] My Ad Title");
  // ... add the rest of metadata as prescribed by the below specification
  /* create ad session object with the reference to the video_session passed and ad info */
  ccl_session_t *ad_session = ccl_session_create(video_session, ad_content_info);
 
  /* ccl_content_info object can be immediately destroyed, if no future metadata update required */
  free(ad_content_info->asset_name);
  // .. release the memory for the rest of the fields
  ccl_content_info_destroy(ad_content_info);
  ad_content_info = 0;

ccl_session_destroy(ad_session);

/* Create an instance of ccl_player_t. This instance shall be available
throughout the player session */
ccl_player_t player = {
    start_monitoring,
    stop_monitoring,
    get_playhead_time,
    get_buffer_length,
    get_rendered_framerate,
    get_min_buffer_length,
    get_player_type,
    get_player_version
};

void start_monitoring(void *player_data, ccl_notifier_t *notifier, ccl_notifier_context_t *notifier_context)
{
  MyMediaPlayer *player = (MyMediaPlayer *) player_data;
  player->notifier = notifier;
  player->notifier_context = notifier_context;
}

void stop_monitoring(void *player_data)
{
  MyMediaPlayer *player = (MyMediaPlayer *) player_data;
  player->notifier = 0;
  player->notifier_context = 0;
}

int ccl_session_report_error (ccl_session_t *session, const char *error_message, int is_fatal)

// report error to the session.
ccl_session_report_error(session, errorMsg, 1);
// cleanup session if no further re-try expected, otherwise keep session
// open until the last re-try
ccl_session_destroy(session);

// report closed_captions_language as "[en]:English” ([langCode]:langName)
ccl->notifier->report_langauge_event(session, CCL_EVENT_CLOSED_CAPTIONS_LANGUAGE, "[en]:English");
// report the subtitles_language = "fr" (consider only language code is available)
// reporting the subtitles will set the previously-reported closed_captions_language = "off"
ccl->notifier->report_langauge_event(session, CCL_EVENT_SUBTITLES_LANGUAGE, "fr");

ccl->notifier->report_langauge_event(session, CCL_EVENT_SUBTITLES_LANGUAGE, "off");

/* Return current media position in milliseconds. -1 if not available */
int get_playhead_time(void *player_data)
{
  MyMediaPlayer *player = (MyMediaPlayer *) player_data;
  return player->position;
}
 
/* Return current buffer length in milliseconds. -1 if not available */
int get_buffer_length(void *player_data)
{
  MyMediaPlayer *player = (MyMediaPlayer *) player_data;
  return player->bufferLength;
}
 
/* Return Current rendered frame rate, in frames per second. -1.0 if not available */
double get_rendered_framerate(void *player_data)
{
  MyMediaPlayer *player = (MyMediaPlayer *) player_data;
  return player->rFramerate;
}
 
/* Return minimum buffer length required for player to continue playing in milliseconds.
 -1 if not available or player state inference by CCL is disabled */
int get_min_buffer_length (void *player_data)
{
  MyMediaPlayer *player = (MyMediaPlayer *) player_data;
  return player->min_buffer_length;
}

// The network connection type that the video player is using.
ccl_notify_network_connection_type ("WiFi");

/* create an attribute */
ccl_dictionary_t *attr = ccl_dictionary_create();
ccl_dictionary_put(attr, "old_quality", "SD");
ccl_dictionary_put(attr, "new_quality", "HD");
ccl_dictionary_put(attr, "player", "STB player");
 
/* send the event */
ccl_session_send_event(video_session, "video_quality_change", attr);
/* release the attribute */
ccl_dictionary_destroy(attr);

// Sample for "share-click" event with 3 arguments
 
/* create an attribute */
ccl_dictionary_t *attr = ccl_dictionary_create();
ccl_dictionary_put(attr, "location", "Toolbar");
ccl_dictionary_put(attr, "assetName", "Sample Video");
ccl_dictionary_put(attr, "shareService", "Facebook");
 
/* send the event */
ccl_send_event("share_click", attr);
/* release the attribute */
ccl_dictionary_destroy(attr);

ccl_cleanup (void);