API reference

Open in ChatGPTOpen in Claude

Every entry point the SDK exposes, grouped by topic and alphabetical within each group.

Calling the SDK

Apart from coralogix_roku_initialize(), which is an ordinary function, every call below is reached through the node the SDK attaches to m.global:

m.global.cxRum.callfunc("<name>", <arguments>)

The name is a string argument to callfunc, which is why these entry points carry no parentheses. m.global.cxRum is invalid before coralogix_roku_initialize() and after shutdown, and a callfunc on invalid crashes the thread, so guard any call that can run outside that window. Every call returns immediately; the SDK builds and sends records on its own thread. After shutdown, every other call is ignored.

Warning

reportErrorLog and reportError are not interchangeable. reportErrorLog writes a log at error severity. reportError writes an error event, a different record type that also marks the session as having errored. Choosing the wrong one puts the data in the wrong place in Coralogix.

Lifecycle methods

coralogix_roku_initialize

Starts the SDK. Call it in main.brs straight after screen.show(), before any other entry point. Calling it a second time changes nothing and warns on the console.

coralogix_roku_initialize(options, globalNode)

Argument	Type	Required	Description
options	Object	Yes	The SDK's configuration. See configuration options
globalNode	Node	Yes	screen.getGlobalNode(). The SDK attaches itself here as m.global.cxRum

Returns

Type	Description
Boolean	true when the SDK started, or when it was already running. false when an option failed validation, in which case the SDK sends nothing and the console names the option

shutdown

Stops the SDK. Both its threads exit, records still queued are dropped, and m.global.cxRum becomes invalid. After shutdown, every other call is ignored.

m.global.cxRum.callfunc("shutdown")

Returns

void

Managing logs

The SDK has a function to report logs of each severity level. Every call below records a log based on its assigned severity level.

Severity levels

A severity level determines the urgency of a log line fom least to most urgent. Levels appear as values included in the record sent to Coralogix.

Field	Value	Severity
DEBUG	1	Debug
VERBOSE	2	Verbose
INFO	3	Info
WARN	4	Warning
ERROR	5	Error
CRITICAL	6	Critical

When the severity is known in advance, call the appropriate function. When the level is decided at runtime, use getSeverity and pass one to reportLog.

getSeverity

Returns the severity levels to pass to reportLog at runtime.

m.global.cxRum.callfunc("getSeverity")

Returns

Type	Description
Object	One field per severity level

reportCritical

Records a log at Critical severity: a failure that stops the channel doing its job.

m.global.cxRum.callfunc("reportCritical", message, options)

Argument	Type	Required	Description
message	String	Yes	The line to record. Truncated at 2048 characters
options	Object	No	{ data, labels }. data is a free-form block dropped whole over 3584 characters; labels apply to this record only

Returns

void

reportDebug

Records a log at Debug severity: detail useful only while developing the channel.

m.global.cxRum.callfunc("reportDebug", message, options)

Argument	Type	Required	Description
message	String	Yes	The line to record. Truncated at 2048 characters
options	Object	No	{ data, labels }. data is a free-form block dropped whole over 3584 characters; labels apply to this record only

Returns

void

reportErrorLog

Records a log at Error severity: a failure worth investigating, recorded as a log.

m.global.cxRum.callfunc("reportErrorLog", message, options)

Argument	Type	Required	Description
message	String	Yes	The line to record. Truncated at 2048 characters
options	Object	No	{ data, labels }. data is a free-form block dropped whole over 3584 characters; labels apply to this record only

Returns

void

reportInfo

Records a log at Info severity: ordinary milestones, such as a screen shown or content loaded.

m.global.cxRum.callfunc("reportInfo", message, options)

Argument	Type	Required	Description
message	String	Yes	The line to record. Truncated at 2048 characters
options	Object	No	{ data, labels }. data is a free-form block dropped whole over 3584 characters; labels apply to this record only

Returns

void

reportLog

Records a log at a severity decided at runtime. Use a named method above when the level is known at the call site.

m.global.cxRum.callfunc("reportLog", severity, message, options)

Argument	Type	Required	Description
severity	Integer	Yes	A level from getSeverity, 1 through 6. An out-of-range or non-numeric value is recorded as Info and warned about on the console
message	String	Yes	The line to record. Truncated at 2048 characters
options	Object	No	{ data, labels }, as for the named level methods

Returns

void

reportVerbose

Records a log at Verbose severity: high-volume tracing you would not keep on in production.

m.global.cxRum.callfunc("reportVerbose", message, options)

Argument	Type	Required	Description
message	String	Yes	The line to record. Truncated at 2048 characters
options	Object	No	{ data, labels }. data is a free-form block dropped whole over 3584 characters; labels apply to this record only

Returns

void

reportWarn

Records a log at Warning severity: something recoverable that a viewer may have noticed.

m.global.cxRum.callfunc("reportWarn", message, options)

Argument	Type	Required	Description
message	String	Yes	The line to record. Truncated at 2048 characters
options	Object	No	{ data, labels }. data is a free-form block dropped whole over 3584 characters; labels apply to this record only

Returns

void

Reporting errors

reportError

Reports an error event: a caught exception, an object you build, or a message. Marks the session as having errored.

m.global.cxRum.callfunc("reportError", error, options)

Argument	Type	Required	Description
error	Object or String	Yes	A caught exception, an object carrying message and errorType, or a plain message string
options	Object	No	{ data, labels }. data is dropped whole over 2048 characters, tighter than a log's

Returns

void

Managing views

endView

Clears the current view. Records that follow carry an empty view name until the next startView.

m.global.cxRum.callfunc("endView")

Returns

void

startView

Names the screen the viewer is on. Every record that follows carries the name, until the next startView or an endView.

m.global.cxRum.callfunc("startView", viewName)

Argument	Type	Required	Description
viewName	String	Yes	The screen name to attach to records. Replaces the current view

Returns

void

Managing labels

getLabels

Returns the channel-wide labels as they currently stand. Labels passed to a single call are not included.

m.global.cxRum.callfunc("getLabels")

Returns

Type	Description
Object	The merged labels from coralogix_roku_initialize() and every setLabels since

setLabels

Merges labels into the channel-wide set. Keys it names are added or replaced; the rest are kept.

m.global.cxRum.callfunc("setLabels", labels)

Argument	Type	Required	Description
labels	Object	Yes	Keys with string, number or boolean values. Ignored whole if the merged set exceeds 512 serialized characters

Returns

void

Managing user context

setUserContext

Replaces the viewer every record from now on describes. A field you don't pass is cleared, so {} signs the viewer out.

m.global.cxRum.callfunc("setUserContext", user)

Argument	Type	Required	Description
user	Object	Yes	user_id, user_name, user_email, account_id, account_name (strings) and user_metadata (an object). An unknown field or a wrong type refuses the whole call. So does exceeding 512 serialized characters

Returns

void. The console reports a rejected call.

Managing sessions

createNewSession

Ends the current session and starts a new one, for example when a viewer signs out.

m.global.cxRum.callfunc("createNewSession")

Returns

Type	Description
String	The ID of the new session

getSessionId

Returns the ID of the current session, without extending it or starting a new one.

m.global.cxRum.callfunc("getSessionId")

Returns

Type	Description
String	The session ID, or "" once the session has ended and the next record has not yet started a new one

reportUserActivity

Refreshes the session's idle timer so it doesn't end prematurely. By default, sessions where the user does not press any key time out after 2 hours. Call reportUserActivity to prevent the session from ending, for example during video playback, which produces no key pressesv of its own.

m.global.cxRum.callfunc("reportUserActivity")

The function refreshes the idle timer only. The four-hour total session limit still applies, so a session ends at four hours however often you call this function.

The SDK applies no throttling of its own. The call sends no record and makes no network request. It reads the session, stamps it with the current time and returns, so calling it on every playback position update is cheap.

When the session already ended, calling this function starts a new session and returns the new session ID. Use this value instead of reading the session ID afterwards.

Returns

Type	Description
String	ID of the session the activity belongs to. When the previous session had already ended, a new session ID.

Reporting network requests

reportNetworkRequest

Reports one HTTP request the SDK did not observe itself. Requests made with CxUrlTransfer are reported automatically and need no call.

m.global.cxRum.callfunc("reportNetworkRequest", request)

Argument	Type	Required	Description
request.method	String	Yes	The HTTP method, such as GET
request.url	String	Yes	The request URL. A request with no usable URL is not reported
request.statusCode	Integer	Yes	The HTTP status. 0 or below means no response arrived
request.durationMs	Integer	Yes	How long the request took, in milliseconds
request.startTime	LongInteger	No	When the request started, epoch milliseconds. Defaults to now
request.failureReason	String	No	The transport's reason text, when the request failed
request.responseContentLength	Integer	No	Response size in bytes

Returns

void

Reading SDK state

getConfig

Returns the configuration the SDK resolved at start-up, with defaults filled in.

m.global.cxRum.callfunc("getConfig")

Returns

Type	Description
Object	The resolved configuration

getDeviceContext

Returns the device description the SDK gathered at start-up and attaches to every record.

m.global.cxRum.callfunc("getDeviceContext")

Returns

Type	Description
Object	The device block as sent

getDeviceState

Returns the device readings the SDK takes per record, rather than once at start-up.

m.global.cxRum.callfunc("getDeviceState")

Returns

Type	Description
Object	The current network, memory and uptime readings

getSessionContext

Returns the session block the SDK attaches to every record.

m.global.cxRum.callfunc("getSessionContext")

Returns

Type	Description
Object	The session block as sent

Observing delivery

Observe the cxExportResult field to show or log whether your telemetry is reaching Coralogix.

m.global.cxRum.observeField("cxExportResult", "onExportResult")

sub onExportResult(event as object)
    result = event.getData()
    print "post "; result.status; " — "; result.chars; " chars"
end sub

The field carries one delivery attempt:

Field	Type	Description
status	Integer	The HTTP status of the upload. 0 or below means no response arrived at all
chars	Integer	The size of the payload sent, in characters

onExportResult runs on the render thread, so calling back into the SDK from inside it is safe.