Roku SDK: Consent Handling
Consent Status
Section titled “Consent Status”You can check the current consent status by calling:
statusEnum = SPConsentStatus()result = m.spEngine.callFunc("getConsentStatus", "YOUR_APPLICATION_ID")
if result.code = 200 status = result.data if status = statusEnum.PENDING ' Show consent banner else if status = statusEnum.COLLECTED ' Proceed normally else if status = statusEnum.RECOLLECTION_REQUIRED ' Trigger re-consent flow end ifend if⚠️
SPConsentStatus()andSPConsentRecollectionReason()must be included in your component before use. See Enum usage guidance.
SPConsentStatus values
Section titled “SPConsentStatus values”| Enum constant | Meaning |
|---|---|
PENDING |
Consent needs to be collected. |
COLLECTED |
Consent has already been obtained. |
RECOLLECTION_REQUIRED |
Consent needs to be re-collected. |
Consent Recollection Reason
Section titled “Consent Recollection Reason”When the SDK determines that consent needs to be recollected (for example, a consent update/re-consent flow), you can fetch the reason by calling:
reasonEnum = SPConsentRecollectionReason()result = m.spEngine.callFunc("getConsentRecollectionReason", "YOUR_APPLICATION_ID")
if result.code = 200 reason = result.data if reason = reasonEnum.EXPIRED ' Handle expired else if reason = reasonEnum.STRUCTURE_CHANGED ' Handle structure change end ifend ifIf no recollection reason is available, result.code will be a non-200 value (e.g., 404).
SPConsentRecollectionReason values
Section titled “SPConsentRecollectionReason values”| Enum constant | Meaning |
|---|---|
EXPIRED |
Consent has expired and needs to be re-collected. |
STRUCTURE_CHANGED |
Packages and services hash mismatch. |
Enum usage guidance
Section titled “Enum usage guidance”BrightScript does not have native enum types. The SDK exposes pseudo-enums through functions that return Associative Arrays, such as SPConsentStatus() and SPConsentRecollectionReason(). These are the authoritative representation for consent status and recollection reasons. The SDK guarantees the contract (what cases are possible), but does not guarantee that the underlying raw string values are stable over time (those are serialization details and may change).
These functions are defined in the SDK’s SPEvents.brs. Roku components only see the scripts they include, so add this line to the XML of every component that calls them:
<script type="text/brightscript" uri="pkg:/source/securePrivacy/constants/SPEvents.brs" />Strongly prefer these functions in app logic.
- Compare against them in your control flow:
if status = statusEnum.PENDINGorif reason = reasonEnum.EXPIRED. - Avoid branching on raw values such as
"Expired","Collected", or"RecollectionRequired". - If you need your own string identifiers, define app-specific keys and create a custom mapping, for example:
reasonEnum = SPConsentRecollectionReason()
if reason = reasonEnum.EXPIRED myReasonKey = "MY_EXPIRED"else if reason = reasonEnum.STRUCTURE_CHANGED myReasonKey = "MY_STRUCTURE_CHANGED"end ifThis guidance applies to all enum values returned from SDK APIs.
Last Consented At
Section titled “Last Consented At”You can get the time the user last gave consent by calling:
result = m.spEngine.callFunc("getLastConsentedAt", "YOUR_APPLICATION_ID")
if result.code = 200 millis = result.data consentedAt = CreateObject("roDateTime") consentedAt.FromSeconds(millis.Left(millis.Len() - 3).ToInt())end ifIt returns the time in epoch milliseconds (UTC), as a String of digits. If consent has not been collected yet, or needs to be re-collected, result.code will be a non-200 value (e.g., 404).
Check If a Package Is Enabled
Section titled “Check If a Package Is Enabled”To check whether a specific package is enabled based on user consent, you can call:
result = m.spEngine.callFunc("getPackage", "YOUR_APPLICATION_ID", "PACKAGE_ID_TO_FIND")
if result.code = 200 and result.data <> invalid if result.data.isEnabled = true ' Enable features end ifend ifThis returns a data message containing the package (packageId, name, isEnabled). You should check isEnabled to determine whether the user has consented.
Collecting Consent
Section titled “Collecting Consent”To launch the consent collection banner, trigger the showBanner action:
m.spEngine.payload = { scene: m.top.GetScene(), applicationId: "YOUR_APPLICATION_ID" }m.spEngine.action = "showBanner"This banner informs users about data collection and provides options to accept or deny consent. You can also display the secondary consent banner by passing your secondary application ID:
m.spEngine.payload = { scene: m.top.GetScene(), applicationId: "YOUR_SECONDARY_APPLICATION_ID" }m.spEngine.action = "showBanner"Customization Options
Section titled “Customization Options”The consent banner supports customization options and displays a “Customize” button that allows users to adjust their consent preferences. When they select the customization button, they will be directed to the Preference Center, where they can:
- View a list of frameworks and their services.
- Enable or disable consent for specific services.
To display the Preference Center directly, trigger the showPreferenceCenter action:
m.spEngine.payload = { scene: m.top.GetScene(), applicationId: "YOUR_APPLICATION_ID" }m.spEngine.action = "showPreferenceCenter"Essential Services
Section titled “Essential Services”You can mark certain services as essential. These services will not be optional for the user to deny, ensuring compliance with the channel’s required functionalities.
Privacy Policy
Section titled “Privacy Policy”The Preferences screen also includes a tab showcasing content related to the app’s privacy policy. This ensures users have access to essential information regarding their data handling.
Data Requests
Section titled “Data Requests”Users can submit a request for their data by filling out a form in the Request Data section. This feature helps manage user data requests in compliance with privacy regulations.
