ccl

Top-level module for the Conviva Client Library. More...

Data Structures
struct	ad_pod_info_t
struct	ccl_settings_t
	Conviva Client Library settings. More...

Macros
#define	CCL_SUCCESS   0
#define	CCL_ERROR   -1
#define	CCL_MAX_URL_LENGTH   256
#define	CCL_MAX_APP_NAME_LENGTH   64
#define	CCL_MAX_USER_ID_LENGTH   64
#define	CCL_APP_MAX_SCREEN_NAME_LEN   1024
#define	CCL_APP_MAX_SCREEN_ID_LEN   38
#define	CCL_MAX_CLIENT_ID_LEN_EXT   49

Typedefs
typedef struct ccl_session	ccl_session_t
	Conviva monitoring session.

Enumerations
enum	ccl_log_level_t {   CCL_LOG_LEVEL_NONE = 0 , CCL_LOG_LEVEL_ERROR = 1 , CCL_LOG_LEVEL_WARN = 2 , CCL_LOG_LEVEL_INFO = 3 ,   CCL_LOG_LEVEL_DEBUG = 4 }
	Log level. More...
enum	ad_player_t { CONTENT = 0 , SEPARATE = 1 , Unknown = 2 }
enum	ad_type_t { CLIENT_SIDE , SERVER_SIDE , AD_TYPE_UNKNOWN }
enum	ad_position_t {   BUMPER = 0 , PREROLL , MIDROLL , POSTROLL ,   POD_POSITION_Unknown = 99 }

Functions
void	ccl_settings_create (ccl_settings_t *settings)
	Create a new ccl_settings_t.
void	ccl_settings_destroy (ccl_settings_t *settings)
	Destroy an existing ccl_settings_t.
int	ccl_init (const char *customer_key, const ccl_platform_t *platform_interface, const ccl_settings_t *settings)
	Initializes the library.
void	ccl_cleanup (void)
	Releases the library and all tied up memory/resources.
ccl_session_t *	ccl_session_create (ccl_content_info_t *content_info)
	Create a new monitoring session.
ccl_session_t *	ccl_ad_session_create (ccl_session_t *content_session, ccl_content_info_t *ad_content_info)
	Create a new AD monitoring session.
int	ccl_session_destroy (ccl_session_t *session)
	Destroy an existing monitoring session.
int	ccl_session_player_attach (ccl_session_t *session, const ccl_player_t *player, void *player_data)
	Link a video player to a monitoring session.
int	ccl_session_player_detach (ccl_session_t *session)
	Unlink current video player from a monitoring session.
int	ccl_session_ad_start (ccl_session_t *session)
	Notify Conviva that preroll advertisement has started.
int	ccl_session_ad_end (ccl_session_t *session)
	Notify Conviva that a preroll ad has ended.
int	ccl_session_report_error (ccl_session_t *session, const char *error_message, int is_fatal)
	Notify Conviva that an error has occurred.
int	ccl_send_event (const char *name, ccl_dictionary_t *attributes)
	Report a custom event to Conviva.
int	ccl_session_send_event (ccl_session_t *session, const char *name, ccl_dictionary_t *attributes)
	Report a custom event to Conviva.
void	ccl_session_update_content_info (ccl_session_t *session, const ccl_content_info_t *content_info)
	Update metadata content for the session.
void	ccl_notify_network_connection_type (const char *type)
	Notify a change of network connection type.
void	ccl_notify_network_signal_strength (double value)
	Notify a change of network wireless signal strength.
void	ccl_notify_network_wifi_link_encryption (const char *name)
	Notify a change of WiFi SSID.
int	ccl_session_set_video_size (ccl_session_t *session, int width, int height)
	Notify Conviva of a video resolution change.
unsigned int	ccl_session_get_session_id (ccl_session_t *session)
	Gets the Conviva session ID for a session.
char *	ccl_get_client_id (void)
	Gets the Conviva Client ID.
int	report_ad_break_started (ccl_session_t *session, ad_player_t ad_player, ad_type_t ad_type, ad_pod_info_t *pod_info)
	Informs content session that the ad break has started.
int	report_ad_break_ended (ccl_session_t *session, ad_player_t ad_player, ad_type_t ad_type, ad_pod_info_t *pod_info)
	Informs content session that the ad break has ended.
int	cat_start_tracker (char *app_name, char *user_id)
	creates tracker for eco
int	cat_stop_tracker (void)
	stop the app tracker

Detailed Description

Top-level module for the Conviva Client Library.

The application should call ccl_init() to initialize the library before making any other calls.
To monitor each viewing experience, a Conviva monitoring session should be created via ccl_session_create() upon playback request by the viewer.
Each monitoring session can be dynamically tied to a video player via ccl_session_player_attach(). Used with ccl_player_t and ccl_notifier_t, video playback data can then be reporting for that monitoring session.
When a video player is no longer relevant for the monitoring session, the link can be severed using ccl_session_player_detach().
When playback for that piece of content ends/fails/is cancelled, the session should be destroyed using ccl_session_destroy().
The application should call ccl_cleanup() to release the library when it is no longer needed.

Macro Definition Documentation

CCL_APP_MAX_SCREEN_ID_LEN

#define CCL_APP_MAX_SCREEN_ID_LEN   38

CCL_APP_MAX_SCREEN_NAME_LEN

#define CCL_APP_MAX_SCREEN_NAME_LEN   1024

CCL_ERROR

#define CCL_ERROR   -1

CCL_MAX_APP_NAME_LENGTH

#define CCL_MAX_APP_NAME_LENGTH   64

CCL_MAX_CLIENT_ID_LEN_EXT

#define CCL_MAX_CLIENT_ID_LEN_EXT   49

CCL_MAX_URL_LENGTH

#define CCL_MAX_URL_LENGTH   256

CCL_MAX_USER_ID_LENGTH

#define CCL_MAX_USER_ID_LENGTH   64

CCL_SUCCESS

#define CCL_SUCCESS   0

Typedef Documentation

ccl_session_t

typedef struct ccl_session ccl_session_t

Conviva monitoring session.

Enumeration Type Documentation

ad_player_t

enum ad_player_t

Enumerator
CONTENT
SEPARATE
Unknown

ad_position_t

enum ad_position_t

Enumerator
BUMPER
PREROLL
MIDROLL
POSTROLL
POD_POSITION_Unknown

ad_type_t

enum ad_type_t

Enumerator
CLIENT_SIDE
SERVER_SIDE
AD_TYPE_UNKNOWN

ccl_log_level_t

enum ccl_log_level_t

Log level.

Enumerator
CCL_LOG_LEVEL_NONE	No logging.
CCL_LOG_LEVEL_ERROR	Display only error logs.
CCL_LOG_LEVEL_WARN	Display only error and warning logs.
CCL_LOG_LEVEL_INFO	Display all logs except debug logs.
CCL_LOG_LEVEL_DEBUG	Display all logs.

Function Documentation

cat_start_tracker()

int cat_start_tracker	(	char *	app_name,
		char *	user_id
	)

creates tracker for eco

Parameters

app_name	specifies name of the application ;
user_id	(optional) specifies the current user of the application.

Returns

• CCL_SUCCESS
• CCL_ERROR

cat_stop_tracker()

int cat_stop_tracker

(

void

)

stop the app tracker

Returns

• CCL_SUCCESS
• CCL_ERROR

ccl_ad_session_create()

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

Create a new AD monitoring session.

A new monitoring session should be created for each piece of Ad content.

Parameters

content_session	instance of video content
ad_content_info	Metadata associated with the ad content to be monitored.

Returns

• A pointer of ccl_session_t on success.
• NULL otherwise.

ccl_cleanup()

void ccl_cleanup

(

void

)

Releases the library and all tied up memory/resources.

Note

This will terminate all active monitoring sessions as well.

ccl_get_client_id()

char * ccl_get_client_id

(

void

)

Gets the Conviva Client ID.

Returns

• Returns pointer to a string which represents client Id

Note

This API shall be called after ccl_init only

ccl_init()

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

Initializes the library.

One-time synchronous call required to initialize the library.

Parameters

customer_key	The Conviva customer key associated with your Conviva account.
platform_interface	Your implementation of ccl_platform_t for your device.
settings	Optional. Custom settings for the library.

Returns

• CCL_SUCCESS
• CCL_ERROR

Warning

All other API calls will fail until the library is properly initialized with a call to ccl_init.

Note

Calling ccl_init() when the library is already initialized will have no effect.

ccl_notify_network_connection_type()

void ccl_notify_network_connection_type

(

const char *

type

)

Notify a change of network connection type.

The type of network connection can be "3G", "4G", "WiFi", "LTE", and etc. When the type is unknown, set "Other".

Parameters

type	network connection type

ccl_notify_network_signal_strength()

void ccl_notify_network_signal_strength

(

double

value

)

Notify a change of network wireless signal strength.

Parameters

value

Signal strength.

ccl_notify_network_wifi_link_encryption()

void ccl_notify_network_wifi_link_encryption

(

const char *

name

)

Notify a change of WiFi SSID.

Parameters

ssid	WiFi SSID.

Notify a change of WiFi Link Encryption.

Example values are "WEP", "WEP2", "WPA", "WPA2".

Parameters

name	Link encryption.

ccl_send_event()

int ccl_send_event	(	const char *	name,
		ccl_dictionary_t *	attributes
	)

Report a custom event to Conviva.

Part of the Conviva Player Insight feature.
Each event has a name and a list of key-value pair attributes.

Parameters

name	Name of the event.
attributes	Optional. Attributes associated with the event.

Returns

• CCL_SUCCESS
• CCL_ERROR

Note

This method can be used without an active monitoring session.

ccl_session_ad_end()

int ccl_session_ad_end

(

ccl_session_t *

session

)

Notify Conviva that a preroll ad has ended.

Use right after playing preroll advertisement.

Parameters

session

Pointer to a ccl_session_t.

Returns

• CCL_SUCCESS
• CCL_ERROR

ccl_session_ad_start()

int ccl_session_ad_start

(

ccl_session_t *

session

)

Notify Conviva that preroll advertisement has started.

Use right before playing preroll advertisement.

Parameters

session

Pointer to a ccl_session_t.

Returns

• CCL_SUCCESS
• CCL_ERROR

ccl_session_create()

ccl_session_t * ccl_session_create

(

ccl_content_info_t *

content_info

)

Create a new monitoring session.

A new monitoring session should be created for each piece of video content, at the time playback is requested by the viewer.

Parameters

content_info

Metadata associated with the content to be monitored.

Returns

• A pointer of ccl_session_t on success.
• NULL otherwise.

ccl_session_destroy()

int ccl_session_destroy

(

ccl_session_t *

session

)

Destroy an existing monitoring session.

An existing monitoring session should be destroyed when video playback for the content ends, fails or is cancelled by the viewer.

Parameters

session

Pointer to the ccl_session_t to destroy.

Returns

• CCL_SUCCESS
• CCL_ERROR

ccl_session_get_session_id()

unsigned int ccl_session_get_session_id

(

ccl_session_t *

session

)

Gets the Conviva session ID for a session.

Parameters

session

Pointer to a ccl_session_t.

Returns

• Session Id of CCL session

Note

This API shall be called after session create and before session destroy

ccl_session_player_attach()

int ccl_session_player_attach	(	ccl_session_t *	session,
		const ccl_player_t *	player,
		void *	player_data
	)

Link a video player to a monitoring session.

Attach a video player to a monitoring session.
Generally used right after ccl_session_create.
To properly handle midroll advertisement, it is sometimes necessary to use this method after a midroll ad.
If you are using multiple video players over the course of a single monitoring session, you may have to call this multiple times as well.

Parameters

session	Pointer to a ccl_session_t.
player	Interface to the video player.
player_data	Context data for the video player.

Returns

• CCL_SUCCESS
• CCL_ERROR

ccl_session_player_detach()

int ccl_session_player_detach

(

ccl_session_t *

session

)

Unlink current video player from a monitoring session.

Detaches the current video player from a monitoring session.
Generally used right before calling ccl_session_destroy.
To properly handle midroll advertisement, it is sometimes necessary to use this method before a midroll ad.
If you are using multiple video players over the course of a single monitoring session, you may have to call this multiple times as well.

Parameters

session

Pointer to a ccl_session_t.

Returns

• CCL_SUCCESS
• CCL_ERROR

ccl_session_report_error()

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

Notify Conviva that an error has occurred.

To report errors from the video player, use set_error instead.

Parameters

session	Pointer to a ccl_session_t.
error_message	A message describing the error.
is_fatal	Whether the error can prevent playback altogether. When in doubt, set to true.

Returns

• CCL_SUCCESS
• CCL_ERROR

Warning

We strongly recommend sticking to static error messages like error codes.
Including dynamic variables like user ID or memory addresses makes spotting error patterns much harder.

ccl_session_send_event()

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

Report a custom event to Conviva.

Part of the Conviva Player Insight feature.
Each event has a name and a list of key-value pair attributes.

Parameters

name	Name of the event.
attributes	Optional. Attributes associated with the event.

Returns

• CCL_SUCCESS
• CCL_ERROR

Note

This method can be used only with an active monitoring session.

ccl_session_set_video_size()

int ccl_session_set_video_size	(	ccl_session_t *	session,
		int	width,
		int	height
	)

Notify Conviva of a video resolution change.

Parameters

session	Pointer to a ccl_session_t.
width	Width of video resolution.
height	Height of video resolution.

Returns

• CCL_SUCCESS
• CCL_ERROR

ccl_session_update_content_info()

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

Update metadata content for the session.

NOTE: Only those metadata values that were not previously set are updated.

Parameters

session	Pointer to a ccl_session_t.
content_info	Metadata associated with the content to be monitored.

ccl_settings_create()

void ccl_settings_create

(

ccl_settings_t *

settings

)

Create a new ccl_settings_t.

Note

All fields are set to their default values.

When setting the gateway_url, free the existing string and set a newly allocated string.

Parameters

settings

instance to ccl_settings_t structure which will be set to default values

ccl_settings_destroy()

void ccl_settings_destroy

(

ccl_settings_t *

settings

)

Destroy an existing ccl_settings_t.

Parameters

settings

instance to ccl_settings_t structure which needs to be destroyed

report_ad_break_ended()

int report_ad_break_ended	(	ccl_session_t *	session,
		ad_player_t	ad_player,
		ad_type_t	ad_type,
		ad_pod_info_t *	pod_info
	)

Informs content session that the ad break has ended.

Parameters

ad_type	specifies type of the ad (server side / client side);
ad_player	informs Conviva SDK which player is used to play the ads - the same as main video content or separate instance.
pod_info	(optional) pod information can be passed

Returns

• CCL_SUCCESS
• CCL_ERROR

report_ad_break_started()

int report_ad_break_started	(	ccl_session_t *	session,
		ad_player_t	ad_player,
		ad_type_t	ad_type,
		ad_pod_info_t *	pod_info
	)

Informs content session that the ad break has started.

Parameters

ad_type	specifies type of the ad (server side / client side);
ad_player	informs Conviva SDK which player is used to play the ads - the same as main video content or separate instance.
pod_info	(optional) pod information can be passed

Returns

• CCL_SUCCESS
• CCL_ERROR