BalkTalk

For developers

Games and the catalog

A public app with a frame address opens on BalkTalk itself. The member is already signed in, so sign-in happens without a redirect, through a small SDK.

How it works

  1. In the portal enter a frame address (https). It is the page of your game that opens in a frame on the app page in the catalog.
  2. Add the SDK to that page:
<script src="https://www.balktalk.net/sdk/v1.js"></script>
  1. Sign the member in and call the API:
await BalkTalk.ready()

const session = await BalkTalk.authorize({
  clientId: 'YOUR_CLIENT_ID',
  scopes: ['scores', 'activity'],
})

const me = await BalkTalk.api('/me')
console.log('Playing:', me.data.display_name)

The first time, BalkTalk asks the member for consent in its own window. After that authorize returns a token right away.

SDK

Call What it does
BalkTalk.isEmbedded() true when the app runs in a frame on BalkTalk
BalkTalk.ready() tells BalkTalk the app has loaded; returns { locale, theme, app }
BalkTalk.authorize({ clientId, scopes }) sign-in without a redirect (PKCE); returns { accessToken, expiresAt, scopes }
BalkTalk.requestCode({ scopes, codeChallenge }) only the sign-in code, for an app that exchanges it on its own server
BalkTalk.api(path, { method, body }) a public API call; the token refreshes itself
BalkTalk.share({ text }) the post window on the Network with your text (the share scope)
BalkTalk.close() closes the frame

Errors are Error objects with a code field: access_denied (the member denied), insufficient_scope, not_embedded (the app is not in a frame), timeout, and the public API codes.

The token lives only in the memory of the page. Do not store it in localStorage.

An app with a server

If you exchange the code for a token on your own server (client secret), take only the code in the browser:

const { code, redirectUri } = await BalkTalk.requestCode({
  scopes: ['scores'],
  codeChallenge: CHALLENGE_FROM_YOUR_SERVER,
})
// send code to your server; it calls https://www.balktalk.net/oauth/token with redirect_uri = redirectUri

In this flow redirect_uri is always your frame address. You do not have to add it to the redirect addresses.

Leaderboards

You create leaderboards in the portal (at most 5 per app). Each has a key, an order (a higher or a lower score is better) and a format (a number, or time in milliseconds).

const result = await BalkTalk.api('/boards/main/scores/me', {
  method: 'PUT',
  body: { score: 1200 },
})
if (result.improved) showNewRecord(result.data.rank)

const top = await BalkTalk.api('/boards/main/scores?limit=10')

Only the member's best score is kept. The leaderboard is also shown on your app page in the catalog.

The score is sent by your app and BalkTalk cannot verify it. If the ranking matters to you, compute and send the score from your server, not from the browser.

“Is playing …” in chats

While the frame is open, BalkTalk shows on its own that the member is using your app. If the app runs on your site, report it yourself once a minute (the activity scope):

await BalkTalk.api('/activity', { method: 'POST' })

Who sees it is up to the member, in their settings (Online status → Radio and games).

The frame

  • The frame is isolated: it has no access to the BalkTalk page, cookies or the member's session. Everything goes through the SDK and the public API.
  • The app cannot redirect the whole page or open new windows. Camera, microphone and location are not available.
  • Full screen, sound and game controllers are allowed.
  • The frame takes the width of the page. Build the game to work from 320 px wide and up, and with touch.
  • The frame address must be https. While developing, http://localhost works, and only you and your testers see such an app.
  • Some browsers ask for permission to access the local network for http://localhost in a frame, or block it. If the frame does not load, put the game on an https address while developing (for example through a tunnel).

An app on its own site

An app without a frame address is in the catalog with a link to its site. There it uses the regular sign in with BalkTalk.

Strictly necessary cookies keep the site running. With your consent we also use optional ones (e.g. analytics) - you can change your choice at any time. Cookie Policy

Strictly necessary cookies keep the site running. With your consent we also use optional ones (e.g. analytics) - you can change your choice at any time. Cookie Policy

Strictly necessary

Always active

The site cannot work without them: sign-in, security, language and your choices. No consent needed and never used for tracking.

  • bt_session cookie · 30 days

    Session: keeps you signed in while you use the site.

    BalkTalk

  • XSRF-TOKEN cookie · 30 days

    Protects forms against forged requests (CSRF).

    BalkTalk

  • remember_web_* cookie · 13 months

    "Remember me": keeps you signed in after closing the browser.

    BalkTalk

  • bt_locale cookie · 12 months

    The language you chose.

    BalkTalk

  • bt_2fa_device cookie · 30 days

    Two-step sign-in: this device does not ask for a code for 30 days (when you choose "Remember this device").

    BalkTalk

  • bt_consent cookie · 12 months

    Your cookie choice (so we do not ask again).

    BalkTalk

  • bt-*, bt:* localStorage · until you clear it

    Browser local storage: theme, language, radio station, recent emoji, chat layout, hidden hints.

    BalkTalk

  • bt_invite cookie · 30 days

    Who invited you to BalkTalk (invite link) – so you both get a reward once you become an active member.

    BalkTalk

  • Cloudflare Turnstile service

    Human check on sign-up (challenges.cloudflare.com) - protects the site from fake accounts.

    Cloudflare, Inc. · Privacy policy

Third-party content

When you open it

Videos, music, GIFs, radio and the map come from other companies' servers. When you open them, those servers see your IP address and may set their own cookies.

  • Google Identity Services service

    One-click sign-in with the Google account you use in the browser ("Continue as …", accounts.google.com). Google sees that you visited the site; we get your name and email only when you click "Continue". Google may set the g_state cookie to remember that you closed the prompt.

    Google Ireland Ltd. · Privacy policy

  • YouTube service

    Videos in the blog and chat (youtube-nocookie.com).

    Google Ireland Ltd. · Privacy policy

  • Deezer service

    Song previews and covers on profiles, the Network and in chat.

    Deezer S.A. · Privacy policy

  • KLIPY service

    GIFs in chat and comments.

    KLIPY Inc. · Privacy policy

  • Radio stations service

    Live stream when you start the radio.

    The selected station's server

  • OpenStreetMap service

    Map in the Nearby module (only with separate map consent).

    OpenStreetMap Foundation · Privacy policy

  • OneSignal service

    Push notifications on this device – loaded only after you turn them on in Settings.

    OneSignal, Inc. · Privacy policy

Analytics

Anonymous visit statistics that help us improve the site. Only with your consent.

  • Google Analytics service

    Visit statistics (which pages are opened, where visitors come from, device) - no ads. Loaded only with your consent.

    Google Ireland Ltd. · Privacy policy

  • _ga cookie · 24 months

    Google Analytics: tells visitors apart (random number, no name or email).

    Google Ireland Ltd. · Privacy policy

  • _ga_0QPMP1EXWV cookie · 24 months

    Google Analytics: remembers the current visit.

    Google Ireland Ltd. · Privacy policy