The Gamestage client asks a fan before optional analytics and storage calls made through the client. It draws the banner and records the choice. Data needed to run the game, such as the session and score, is processed separately. gamestage deploy checks consent behaviour, but those checks do not cover every possible recording path in a game's own code.
Quickstart
Name who is asking and link your privacy policy, in gamestage.settings.json beside gamestage.yaml. A deploy writes both into Studio:
{
"consent_brand_name": "Arsenal",
"privacy_policy_url": "https://www.arsenal.com/privacy-policy"
}Then load the client and start the game. The banner appears on its own the first time a fan opens the game:
const game = await gamestage.start({
consentBanner: { settingsIn: document.querySelector("footer") },
});settingsIn puts a "Privacy settings" button in your footer, so a fan can change their mind later. Leave it out and the banner pins a small "Privacy settings" pill in the bottom corner of the screen, outside the page's layout, so a game sized to fit the screen does not gain a scrollbar. Pass null only when your own control calls game.consent.openSettings().
Check it the way a new fan would meet it:
npx gamestage@latest verifyThe consent line passes when a consent control appears before anything is sent, and nothing is sent after the fan says no. The consent-owner line passes when the brand name and the privacy policy link are both set.
What a fan sees
A compact card floating near the foot of the screen, clear of the game's own pill nav and pinned main button: two lines naming who is asking and why, an underlined Privacy policy link, Accept (filled in the game's accent) and Reject (outlined) at the same size side by side, a small Manage preferences link for choosing one category at a time, and a × in the corner. It takes the game's colours and font from its Studio palette when they are readable together. The game stays playable underneath it.
× closes the card without answering. Optional analytics and storage remain off, and the card comes back on the next visit.
The fan is asked once per game, on each device, until the producer changes the privacy policy version in Studio.
| Category | What it allows | On by default |
|---|---|---|
necessary | Playing the game: a fan's session and their round in progress. | Always on |
analytics | Monterosa Analytics, and PostHog or Google if the creator turns them on. | No |
marketing | Offers and news from the game's owner. | No |
functional | Remembering a fan's preferences on the device. | No |
These are the Monterosa SDK's own category names, so an app's answer needs no translating on the way in.
A game with Ads switched on records that it showed the shop panel only when the fan has agreed to marketing.
Change the words
Every word on the banner is the producer's, in Studio under Wording. An empty field shows the default.
| Studio setting | Default |
|---|---|
consent_brand_name | None. Required: verify fails and deploy refuses while it is empty. Name your own brand, the one fans know: the banner reads "Arsenal would like to record analytics on how you play…". verify and deploy refuse "Monterosa" here, and a monterosa.co privacy policy, on any game but Monterosa's own: a gamestage.ai game, or one made by somebody signed in with a monterosa.co.uk account. |
consent_title | Your privacy |
consent_detail | {brand} would like to record analytics on how you play, so we can improve the game. We only do this if you agree. Data needed to run the game, such as your scores, is processed on the basis of legitimate interests. |
consent_accept_label | Accept |
consent_reject_label | Reject |
consent_choose_label | Manage preferences |
consent_save_label | Save my choices |
consent_analytics_label | Measure how the game is played |
consent_marketing_label | Offers and news from the game's owner |
consent_functional_label | Remember my preferences |
consent_settings_label | Privacy settings |
privacy_policy_url | None. Required, and must be https: verify fails and deploy refuses while it is empty. |
consent_policy_version | 1. Change it when your privacy policy changes, and every fan is asked again. |
Pass consent in from an app that embeds the game
A club app that embeds a game has usually asked its fan already. Pass that answer in and the game does not show its own banner.
With the Monterosa SDK, set it in the host page. It reaches the game on its own, and the game's banner and Privacy settings step aside for it:
import { setConsentState } from "@monterosa/sdk-consent-kit";
setConsentState({ necessary: true, analytics: true, marketing: false, functional: true });Without the SDK: list the host page in embed_origins
Any website can put a game in a frame, so the game reads a consent message only from a page the producer has named. In Studio, under Wording, set embed_origins to the exact address of the page around the game:
https://www.arsenal.com, https://app.arsenal.comEach entry is a scheme, a host and an optional port, separated by commas. Write it the way the browser reports the page's origin: no path, no query, no *. An entry that is not an exact origin is dropped. http:// works only for localhost and 127.0.0.1. Empty is the default, and with it the game reads no consent message at all and asks every fan itself.
Then post the answer into the game's frame, naming the policy version it answers:
frame.contentWindow.postMessage(
{
type: "gamestage:consent",
policyVersion: "1",
categories: { analytics: true, marketing: false, functional: true },
},
new URL(frame.src).origin,
);policyVersion is the game's consent_policy_version from Studio, 1 unless the producer changed it. A missing category is a no. Post again with new categories to change or withdraw the answer.
| The game ignores a message when | Why |
|---|---|
| it comes from anything but the frame's own parent | Another frame or window on the page is not the host. |
the parent's origin is not in embed_origins | The producer has not named that site. |
policyVersion is missing or is not the game's current version | An answer to another policy is no answer, the same rule as a fan's stored choice. |
type is not gamestage:consent, or categories is not an object | It is not a consent message. |
| the fan has already answered the game's own banner for this policy version | A fan's own choice always comes first. The host's message never replaces a stored yes or a stored no. |
A host's message does not lock the fan out. Privacy settings stays on the page, and once the fan saves a choice there, that choice is the one the game uses, whatever the host posts afterwards.
When your organisation's app owns consent
If every game in your organisation runs inside your own app, and that app asks for consent and age itself, Monterosa can set that on your organisation's profile. Your games then draw no banner, no Privacy settings and no age gate, and record nothing until your app passes consent in as above. See your organisation.
Read the answer in your game
game.consent holds the answer. You rarely need it: the client's gates already read it.
| Member | Returns | What it is for |
|---|---|---|
record() | ConsentRecord or null | The full answer: categories, source (host, fan or default), decidedAt, policyVersion, jurisdiction. null while nobody has answered. |
needed() | boolean | True when the game must still ask. |
hostDecides() | boolean | True when the embedding app answered through the Monterosa SDK, or a host consent manager such as OneTrust runs the page. Hide your own privacy link when it is. A message from a page in embed_origins does not make it true, because the fan can still change that answer. |
decide(categories) | boolean | Records the fan's answer. False where the host decides. |
openSettings() | nothing | Opens the choices again. |
onChange(listener) | an unsubscribe function | Called whenever any authority changes the answer. |
Draw your own consent screen
A Gamestage UI game uses the consent component, which reads and writes the same record. Turn the client's banner off so there are not two:
const game = await gamestage.start({ consentBanner: false });Any screen of your own must carry data-gs-component="consent", offer reject as plainly as accept, and call game.consent.decide. verify and deploy check it by loading the game as a new fan, so a page that turns the banner off and asks nobody is refused.
When the check fails
verify or deploy says | What to do |
|---|---|
| The page sent analytics before the fan answered | Send events through game.track, which waits for consent. Remove any tracking script loaded directly in the page. |
| The banner would not say who is asking | Add consent_brand_name and privacy_policy_url to gamestage.settings.json. |
| No consent banner appeared | Load the Gamestage client and leave consentBanner on, or draw the consent component. Check the console for an error that stopped gamestage.start(). |
| The fan said no and the page still sent analytics | Something in the page tracks without the client. Remove it. |
| Consent checked by reading the page, not in a browser | No Chrome on this machine. Install Chrome, or set GAMESTAGE_CHROME, for the full check. |
If your game records nothing about fans at all, set identity.consent.analytics_requires_consent: false in gamestage.yaml and no banner is required. That is your declaration to answer for.