Kako radi
- U portalu upiši adresu okvira (https). To je stranica tvoje igre koja se otvara u okviru na stranici aplikacije u katalogu.
- Na tu stranicu dodaj SDK:
<script src="https://www.balktalk.net/sdk/v1.js"></script>
- Prijavi člana i zovi API:
await BalkTalk.ready()
const session = await BalkTalk.authorize({
clientId: 'TVOJ_CLIENT_ID',
scopes: ['scores', 'activity'],
})
const me = await BalkTalk.api('/me')
console.log('Igra', me.data.display_name)
Prvi put BalkTalk pita člana za pristanak u svom prozoru. Sljedeći put authorize odmah vrati token.
SDK
| Poziv | Šta radi |
|---|---|
BalkTalk.isEmbedded() |
true kad aplikacija radi u okviru na BalkTalku |
BalkTalk.ready() |
javi da je aplikacija učitana; vraća { locale, theme, app } |
BalkTalk.authorize({ clientId, scopes }) |
prijava bez preusmjeravanja (PKCE); vraća { accessToken, expiresAt, scopes } |
BalkTalk.requestCode({ scopes, codeChallenge }) |
samo kod prijave, za aplikaciju koja ga mijenja za token na svom serveru |
BalkTalk.api(path, { method, body }) |
poziv javnog API-ja; token se obnavlja sam |
BalkTalk.share({ text }) |
prozor za objavu na Mreži sa tvojim tekstom (dozvola share) |
BalkTalk.close() |
zatvori okvir |
Greške su Error sa poljem code: access_denied (član je odbio), insufficient_scope, not_embedded (aplikacija nije u okviru), timeout, te kodovi javnog API-ja.
Token živi samo u memoriji stranice. Ne spremaj ga u localStorage.
Aplikacija sa serverom
Ako kod mijenjaš za token na svom serveru (tajni ključ), u pregledniku uzmi samo kod:
const { code, redirectUri } = await BalkTalk.requestCode({
scopes: ['scores'],
codeChallenge: IZAZOV_SA_TVOG_SERVERA,
})
// pošalji code svom serveru; on zove https://www.balktalk.net/oauth/token sa redirect_uri = redirectUri
redirect_uri je u ovom toku uvijek tvoja adresa okvira. Ne moraš je upisivati među povratne adrese.
Rang liste
Rang liste praviš u portalu (najviše 5 po aplikaciji). Svaka ima ključ, redoslijed (veći ili manji rezultat je bolji) i prikaz (broj ili vrijeme u milisekundama).
const result = await BalkTalk.api('/boards/glavna/scores/me', {
method: 'PUT',
body: { score: 1200 },
})
if (result.improved) showNewRecord(result.data.rank)
const top = await BalkTalk.api('/boards/glavna/scores?limit=10')
Čuva se samo najbolji rezultat člana. Rang lista se vidi i na stranici tvoje aplikacije u katalogu.
Rezultat šalje tvoja aplikacija i BalkTalk ga ne može provjeriti. Ako ti je poredak važan, rezultat računaj i šalji sa svog servera, ne iz preglednika.
„Igra …” u razgovorima
Dok je okvir otvoren, BalkTalk sam prikazuje da član koristi tvoju aplikaciju. Ako aplikacija radi na tvom sajtu, javljaj se sama jednom u minuti (dozvola activity):
await BalkTalk.api('/activity', { method: 'POST' })
Ko to vidi određuje član u svojim postavkama (Online status → Radio i igre).
Okvir
- Okvir je izolovan: nema pristup stranici BalkTalka, kolačićima ni sesiji člana. Sve ide kroz SDK i javni API.
- Aplikacija ne može preusmjeriti cijelu stranicu ni otvarati nove prozore. Kamera, mikrofon i lokacija nisu dostupni.
- Dozvoljeni su cijeli ekran, zvuk i kontroler za igre.
- Okvir zauzima širinu stranice. Napravi igru da radi od 320 px širine naviše i na dodir.
- Adresa okvira mora biti https. Dok razvijaš može
http://localhost, a takvu aplikaciju vide samo ti i testeri. - Neki preglednici za
http://localhostu okviru traže dozvolu za pristup lokalnoj mreži ili ga blokiraju. Ako se okvir ne učita, igru dok razvijaš stavi na https adresu (npr. kroz tunel).
Aplikacija na svom sajtu
Aplikacija bez adrese okvira je u katalogu sa linkom na svoj sajt. Tamo koristi običnu prijavu preko BalkTalka.