Skip to content

Roku SDK: Advanced Usage

You can listen to consent events by observing the consentEvent field on your SPConsentEngine node, and stop listening by unobserving it, for example when your component is removed:

' Start listening
m.spEngine.ObserveField("consentEvent", "onConsentAction")
sub onConsentAction(event as Object)
evt = event.GetData()
if evt = invalid then return
' Custom logic
end sub
' Stop listening
m.spEngine.UnobserveField("consentEvent")

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

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.

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.

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.

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"

The init action creates a session-bound consent engine context. Any value you obtain from that session context should be treated as valid only for the current session.

Triggering the clearSession action:

  • Invalidates the current SDK session
  • Invalidates previously obtained session-bound data
  • Wipes persisted SDK state and in-memory caches

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

Incorrect usage

  • Initialise SDK
  • Trigger the clearSession action
  • Continue using the engine to query consent status
m.spEngine.action = "clearSession"
' Do not reuse a pre-clear session
status = m.spEngine.callFunc("getConsentStatus", "YOUR_APPLICATION_ID")

Correct usage

  • Initialise SDK
  • Use the engine
  • Trigger the clearSession action
  • Trigger the init action again
  • Wait for initResult before any further SDK calls
' ... use SDK
m.spEngine.action = "clearSession"
m.spEngine.payload = {
applicationId: "YOUR_APPLICATION_ID"
}
m.spEngine.action = "init"
' Wait for initResult before further SDK calls