Skip to content

Roku SDK: Consent Handling

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 if
end if

⚠️ SPConsentStatus() and SPConsentRecollectionReason() must be included in your component before use. See Enum usage guidance.

Enum constant Meaning
PENDING Consent needs to be collected.
COLLECTED Consent has already been obtained.
RECOLLECTION_REQUIRED Consent needs to be re-collected.

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 if
end if

If no recollection reason is available, result.code will be a non-200 value (e.g., 404).

Enum constant Meaning
EXPIRED Consent has expired and needs to be re-collected.
STRUCTURE_CHANGED Packages and services hash mismatch.

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.PENDING or if 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 if

This guidance applies to all enum values returned from SDK APIs.

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 if

It 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).

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 if
end if

This returns a data message containing the package (packageId, name, isEnabled). You should check isEnabled to determine whether the user has consented.

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"

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"

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.

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.

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.