Roku SDK: Advanced Usage
Listening to Consent Events
Section titled “Listening to Consent Events”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 listeningm.spEngine.ObserveField("consentEvent", "onConsentAction")
sub onConsentAction(event as Object) evt = event.GetData() if evt = invalid then return ' Custom logicend sub
' Stop listeningm.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.
Debugging and Logs
Section titled “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 = trueThese 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)
Section titled “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.dataend ifThis 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
Section titled “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.dataend ifIt returns a country code like US-CA or IN based on the user’s region.
Clearing Session
Section titled “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 & Reinitialisation
Section titled “Session Lifecycle & Reinitialisation”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
initaction before making any further SDK calls. Reusing the engine without reinitialising can lead to undefined or broken behavior.
Incorrect usage
- Initialise SDK
- Trigger the
clearSessionaction - Continue using the engine to query consent status
m.spEngine.action = "clearSession"
' Do not reuse a pre-clear sessionstatus = m.spEngine.callFunc("getConsentStatus", "YOUR_APPLICATION_ID")Correct usage
- Initialise SDK
- Use the engine
- Trigger the
clearSessionaction - Trigger the
initaction again - Wait for
initResultbefore 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