Roku SDK: Advanced Usage

Listening to Consent Events

You can listen to consent events by observing the consentEvent field on your SPConsentEngine node:

m.spEngine.ObserveField("consentEvent", "onConsentAction")

sub onConsentAction(event as Object)
    evt = event.GetData()
    if evt = invalid then return
    ' Custom logic
end sub

Every consent outcome (accept / decline / customize / save / cancel) lands here. You can use this to refresh your UI or unlock features after the user provides consent.

Debugging and Logs

To enable detailed logs for debugging during development, activate the debugEnabled flag provided by the SDK on your engine node:

m.spEngine.debugEnabled = true

These settings will enable:

• Error Logs – to capture critical issues.
• Info Logs – for general SDK activity and flow.
• Warning Logs – to monitor potential misconfigurations or unexpected behavior.

⚠️ Tip: Disable logging in production to avoid exposing sensitive data.

Handling Unique Client ID (optional)

Each time the app is installed (fresh install) or during a new session, Secure Privacy TV Consent SDK generates a unique clientId for the user. This clientId can be retrieved by calling the following method.

result = m.spEngine.callFunc("getClientId", "YOUR_APPLICATION_ID")
if result.code = 200
    clientId = result.data
end if

This clientId can be used to associate the user’s consent with internal identifiers within your app or backend systems. You can also use this clientId for custom user identification and to ensure accurate tracking of consent preferences.

Get Country Code

You can get the country code detected by the SDK using:

result = m.spEngine.callFunc("getLocale", "YOUR_APPLICATION_ID")
if result.code = 200
    countryCode = result.data
end if

It returns a country code like US-CA or IN based on the user’s region.

Clearing Session

To clear the session, trigger the clearSession action. This method is useful when you want to ensure that all local session-specific sdk data is cleared. It is typically used when a user logs out or resets their preferences.

m.spEngine.action = "clearSession"

Session Lifecycle & Reinitialization

Initializing the SDK with the init action creates a session-bound context. Values obtained through the engine should be treated as valid only while the session remains active.

Calling the clearSession action:

• Invalidates the current SDK session
• Wipes persisted SDK state and in-memory caches

⚠️ Warning: After clearing/resetting the session, you must reinitialize the SDK with the init action before making any further SDK calls. Reusing the engine without re-initializing can lead to undefined or broken behavior.

Incorrect usage

• Initialize SDK
• Send clearSession action
• Continue using the engine to query consent status

m.spEngine.action = "clearSession"

' Do not reuse a pre-clear session state
status = m.spEngine.callFunc("getConsentStatus", "YOUR_APPLICATION_ID")

Correct usage

• Initialize SDK
• Use the engine
• Send clearSession action
• Send init action again

m.spEngine.action = "clearSession"

m.spEngine.payload = {
    applicationId: "YOUR_APPLICATION_ID"
}
m.spEngine.action = "init"

' Wait for initialization to complete before further calls