# API reference

Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Frum%2Fsdk-installation%2Froku%2Ffeatures%2Fapi-reference.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fcoralogix.com%2Fdocs%2Fuser-guides%2Frum%2Fsdk-installation%2Froku%2Ffeatures%2Fapi-reference.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

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

## Calling the SDK[​](#calling-the-sdk "Direct link to Calling the SDK")

Apart from [`coralogix_roku_initialize()`](#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`](#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`](#reporterror) are not interchangeable. `reportErrorLog` writes a **log** at [error severity](#severity-levels). `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[​](#lifecycle-methods "Direct link to Lifecycle methods")

### coralogix\_roku\_initialize[​](#coralogix_roku_initialize "Direct link to 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](https://coralogix.com/docs/user-guides/rum/sdk-installation/roku/configuration/options.md#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[​](#shutdown "Direct link to 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[​](#managing-logs "Direct link to 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[​](#severity-levels "Direct link to 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`](#getseverity) and pass one to [`reportLog`](#reportlog).

### getSeverity[​](#getseverity "Direct link to getSeverity")

Returns the [severity levels](#severity-levels) to pass to [`reportLog`](#reportlog) at runtime.

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

**Returns**

| Type   | Description                                      |
| ------ | ------------------------------------------------ |
| Object | One field per [severity level](#severity-levels) |

### reportCritical[​](#reportcritical "Direct link to 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[​](#reportdebug "Direct link to 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[​](#reporterrorlog "Direct link to 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[​](#reportinfo "Direct link to 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[​](#reportlog "Direct link to 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`](#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[​](#reportverbose "Direct link to 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[​](#reportwarn "Direct link to 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[​](#reporting-errors "Direct link to Reporting errors")

### reportError[​](#reporterror "Direct link to 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[​](#managing-views "Direct link to Managing views")

### endView[​](#endview "Direct link to endView")

Clears the current view. Records that follow carry an empty view name until the next [`startView`](#startview).

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

**Returns**

`void`

### startView[​](#startview "Direct link to startView")

Names the screen the viewer is on. Every record that follows carries the name, until the next `startView` or an [`endView`](#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[​](#managing-labels "Direct link to Managing labels")

### getLabels[​](#getlabels "Direct link to 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`](#setlabels) since |

### setLabels[​](#setlabels "Direct link to 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[​](#managing-user-context "Direct link to Managing user context")

### setUserContext[​](#setusercontext "Direct link to 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[​](#managing-sessions "Direct link to Managing sessions")

### createNewSession[​](#createnewsession "Direct link to 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[​](#getsessionid "Direct link to 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[​](#reportuseractivity "Direct link to 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[​](#reporting-network-requests "Direct link to Reporting network requests")

### reportNetworkRequest[​](#reportnetworkrequest "Direct link to 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[​](#reading-sdk-state "Direct link to Reading SDK state")

### getConfig[​](#getconfig "Direct link to 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[​](#getdevicecontext "Direct link to 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[​](#getdevicestate "Direct link to 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[​](#getsessioncontext "Direct link to 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[​](#observing-delivery "Direct link to 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.