Documentazione per i giochi web
Collega il tuo gioco del browser agli eventi della live di TikTok tramite l'app desktop di TikAresV.
Che cos'è e come funziona
TikAresV è un'app desktop che legge gli eventi della live di TikTok dello streamer (regali, commenti, like, follower, condivisioni, abbonamenti, ingressi e spettatori) e li consegna al tuo gioco.
L'app apre sul computer dello streamer una API locale su 127.0.0.1, e il tuo gioco, che gira nel browser di quello stesso computer, si collega a essa con una API key.
- La API locale esiste solo finché l'app desktop è aperta sul computer dove gira il gioco.
- Ogni evento arriva con un
idstabile, quindi il tuo gioco può ignorare quelli che ha già elaborato. - Lo streamer definisce nell'app quale azione scatta con ogni regalo, commento o like, e il tuo gioco esegue solo le azioni che riceve.
- Puoi ricevere gli eventi tramite WebSocket, che è la soluzione più comoda nel browser, oppure tramite richiesta periodica (long-poll) se preferisci HTTP semplice.
Per ricevere eventi ti servono solo la API key del tuo gioco, un browser sul computer dello streamer e le istruzioni di questa pagina.
Registrazione del gioco e API key
La registrazione dei giochi la fa il team di TikAresV, quindi scrivici per registrare il tuo.
Contatta il team di TikAresVQuando il tuo gioco sarà registrato riceverai i seguenti dati.
- Il
game_idè l'identificatore univoco del tuo gioco. - La API key ha la forma
tkv_live_più 32 caratteri alfanumerici e viene mostrata una sola volta, quindi conservala subito. - Il
game_guidviene fornito solo per i giochi di Roblox.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSe devi cambiare la key, il team ne genera una nuova e la precedente resta valida per 24 ore (86400 secondi) così puoi aggiornare il tuo gioco senza interruzioni.
Tratta la key come una password del tuo gioco e non pubblicarla in repository aperti che non siano tuoi.
Autenticazione con la API key
Ogni chiamata che consegna eventi o configurazione si autentica con la API key del tuo gioco, che ha la forma tkv_live_ seguita da 32 caratteri alfanumerici.
| Rotta | Credenziale |
|---|---|
GET /v1/events | key=<api_key> | x-api-key |
GET /v1/events/poll | x-api-key |
GET /v1/config | x-api-key |
GET /v1/status | — |
GET http://127.0.0.1:17920/v1/events/poll?wait=0 HTTP/1.1
Host: 127.0.0.1:17920
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxLa key viaggia dentro il codice del tuo gioco e lo identifica come gioco presso l'app, quindi non condividerla con altri giochi.
- Il WebSocket riceve la key nel parametro
keydell'URL, perché il browser non permette di inserire intestazioni in un WebSocket. - Le rotte HTTP
/v1/events/polle/v1/configricevono la key solo nell'intestazionex-api-key, e il parametrokeyviene ignorato. - La rotta
/v1/statusnon richiede una key, quindi serve a sapere se l'app è aperta prima di connettersi.
Avvio rapido
Con questi passaggi il tuo gioco riceve il primo evento in pochi minuti.
- Chiedi al team di TikAresV di registrare il tuo gioco e conserva la API key che ricevi, perché viene mostrata una sola volta.
- Chiedi allo streamer di aprire l'app desktop di TikAresV e di accedere.
- Copia l'esempio di questa sezione in un file
.htmle sostituisci il segnaposto della API key con la tua. - Apri il file nel browser dello stesso computer dove gira l'app, e se Chrome chiede l'accesso alla rete locale, accetta.
- Chiedi allo streamer di entrare nel suo gioco nell'app, di modificare una regola e di premere il pulsante Prova.
- Verifica che il registro della pagina mostri una riga con l'
iddell'evento di prova e il nome dell'azione. - Quando funziona, sostituisci la funzione
runActioncon il codice del tuo gioco per ogni azione.
<!doctype html>
<html lang="es">
<head>
<meta charset="utf-8">
<title>TikAresV: juego web de ejemplo</title>
</head>
<body>
<pre id="log"></pre>
<script>
const API_KEY = 'tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'; // la key de tu juego
const PORT = 17920; // C-020
const TYPES = 'gift,comment,like,follow,share,subscribe,join';
const BACKOFF_S = [1, 2, 4, 8, 16, 30]; // C-028
let cursor = null;
let attempt = 0;
function log(line) {
document.getElementById('log').textContent += line + '\n';
}
// Aquí va el código de tu juego para cada acción.
function runAction(actionKey, params) {
console.log('acción', actionKey, params);
}
function handleEvent(ev) {
for (const action of ev.actions) {
log(ev.id + ' ' + action.action_key);
for (let i = 0; i < (action.repeat || 1); i++) runAction(action.action_key, action.params);
}
}
function retryIn(seconds) {
const jitter = 0.8 + Math.random() * 0.4;
setTimeout(connect, seconds * 1000 * jitter);
}
function onClose(code) {
if (code === 4401) return log('key inválida (4401): cámbiala antes de reconectar');
if (code === 1009) return log('mensaje demasiado grande (1009): corrige el cliente');
if (code === 1000) return log('conexión cerrada por el juego (1000)');
if (code === 4403) return retryIn(30); // el plan del streamer no está vigente
retryIn(BACKOFF_S[Math.min(attempt++, BACKOFF_S.length - 1)]); // 1001, 1008, 4408 y caídas
}
function connect() {
let url = 'ws://127.0.0.1:' + PORT + '/v1/events?key=' + encodeURIComponent(API_KEY) + '&types=' + TYPES;
if (cursor) url += '&cursor=' + encodeURIComponent(cursor);
const ws = new WebSocket(url);
ws.onmessage = (message) => {
const msg = JSON.parse(message.data);
if (msg.type === 'hello') {
attempt = 0;
if (msg.data.reset) log('la app se reinició: solo llegarán eventos nuevos');
} else if (msg.type === 'event') {
cursor = msg.data.cursor;
handleEvent(msg.data.event);
} else if (msg.type === 'ping') {
ws.send(JSON.stringify({ type: 'pong', data: { ts: msg.data.ts } }));
} else if (msg.type === 'config.changed') {
log('config.changed ' + msg.data.config_version);
} else if (msg.type === 'error') {
log('error ' + msg.data.code);
}
};
ws.onclose = (close) => onClose(close.code);
}
connect();
</script>
</body>
</html>
Se qualcosa non funziona, consulta la tabella degli errori e la sezione sulla risoluzione dei problemi più sotto.
Stato dell'app: GET /v1/status
Questa rotta indica se l'app è aperta e se può servire eventi, e non richiede una API key.
GET http://127.0.0.1:17920/v1/status{
"api": "local/v1",
"agent_version": "0.1.245",
"port": 17920,
"server_time": "2026-10-03T21:15:30.000Z",
"tiktok_state": "streaming",
"live": { "active": true, "observer": false, "started_at": "2026-10-03T21:15:00.000Z" },
"serving": true,
"serving_reason": "live_started_with_token",
"connected_games": 1,
"max_connected_games": 3,
"control_channel": "websocket"
}- Il campo
servingètruequando l'app può consegnare eventi al tuo gioco. - Il campo
serving_reasonspiega perché serve o perché non serve, eno_valid_tokensignifica che il piano dello streamer non è valido. - Il campo
tiktok_statevaledisconnectedsenza acquisizione,waitingin attesa della live estreamingcon la live in corso. - I campi
connected_gamesemax_connected_gamesindicano quanti giochi sono collegati e quanti ne consente il piano.
Connessione tramite WebSocket: GET /v1/events
Il WebSocket consegna gli eventi non appena arrivano, ed è il metodo consigliato per i giochi web.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41- Il parametro
keyè obbligatorio e contiene la API key codificata conencodeURIComponent. - Il parametro
typesè facoltativo, elenca i tipi separati da virgole senza spazi, e se manca si ricevono tutti e otto i tipi. - Il parametro
cursorè facoltativo e riprende la consegna dall'ultimo evento elaborato dal tuo gioco.
Subito dopo la connessione, l'app invia un messaggio hello con lo stato della sessione.
{
"type": "hello",
"data": {
"api": "local/v1", "agent_version": "0.1.245", "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"game_name": "Juego de prueba", "platform": "web", "types": ["gift", "comment"],
"cursor": "1791062100000-41", "reset": false, "config_version": 7,
"live": { "live_id": "01a1039e-c820-7028-9d1f-b2da68991b17", "unique_id": "ana_streams", "observer": false,
"started_at": "2026-10-03T21:15:00.000Z" },
"server_time": "2026-10-03T21:15:30.010Z"
}
}{ "type": "event", "data": { "cursor": "1791062100000-42", "event": { "v": 1, "id": "tt:7421234567890001001", "…": "…" } } }
{ "type": "config.changed", "data": { "config_version": 8 } }
{ "type": "ping", "data": { "ts": 1791062130000 } }
{ "type": "error", "data": { "code": "LOCAL_ACCESS_EXPIRED", "message": "local access expired", "details": { "reason": "no_valid_token" } } }L'app invia un ping ogni 30 secondi e il tuo gioco deve rispondere pong con lo stesso ts entro 10 secondi, altrimenti l'app chiude la connessione con il codice 4408.
{ "type": "pong", "data": { "ts": 1791062130000 } }Richiesta periodica: GET /v1/events/poll
Questa rotta è l'alternativa ai WebSocket per i client che sanno fare solo richieste HTTP, e attende fino a wait secondi prima di rispondere vuota.
GET http://127.0.0.1:17920/v1/events/poll?cursor=1791062100000-41&wait=20&types=gift,comment&limit=100
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx| Parametro | Obbligatorio | Predefinito | Intervallo |
|---|---|---|---|
cursor | no | — | ^[0-9]{13}-[0-9]{1,19}$ |
wait | no | 0 | 0–25 (C-021) |
types | no | gift,comment,like,follow,share,subscribe,join,viewers | gift … viewers |
limit | no | 100 | 1–100 (C-057) |
{
"events": [ { "v": 1, "id": "tt:7421234567890001001", "type": "gift", "…": "…" } ],
"cursor": "1791062100000-43",
"reset": false,
"has_more": false,
"config_version": 7,
"live": { "live_id": "01a1039e-c820-7028-9d1f-b2da68991b17", "unique_id": "ana_streams", "observer": false,
"started_at": "2026-10-03T21:15:00.000Z" },
"server_time": "2026-10-03T21:15:30.010Z"
}- Ripeti la richiesta non appena ricevi la risposta, inviando il
cursordella risposta precedente. - Il campo
has_moreètruequando sono rimasti eventi a causa del limitelimit, e allora devi richiedere di nuovo senza attendere. - Se smetti di fare richieste per 60 secondi, l'app considera il tuo gioco disconnesso.
Regole in vigore: GET /v1/config
Questa rotta restituisce le regole che lo streamer ha configurato per il tuo gioco, e serve a mostrare aiuti sullo schermo.
GET http://127.0.0.1:17920/v1/config
x-api-key: tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
If-None-Match: "cfg-7"{ "game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e", "config_version": 7, "updated_at": "2026-10-03T20:58:41.512Z",
"is_default": false, "config": { "schema": "config/v1", "rules": [ { "rule_id": "r-rosa-mensaje", "…": "…" } ] } }Il tuo gioco non ha bisogno di interpretare le regole, perché ogni evento porta già le sue azioni risolte.
Contenuto di ogni evento
Ogni evento ha gli stessi campi comuni, e ogni tipo aggiunge il proprio oggetto con i dati specifici.
{
"v": 1,
"id": "tt:7421234567890001001",
"type": "gift",
"ts": "2026-10-03T21:15:04.512Z",
"live_id": "01a1039e-c820-7028-9d1f-b2da68991b17",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421234567890123456",
"test": false,
"user": { "user_id": "…", "unique_id": "…", "nickname": "…", "avatar_url": "…", "badges": { "…": "…" } },
"gift": { "…": "…" }, "comment": null, "like": null, "viewers": null, "subscribe": null,
"actions": [
{ "action_key": "show_message", "params": { "text": "…", "color": "#FF3366" }, "rule_id": "r-rosa-mensaje", "repeat": 1 }
]
}- Il campo
vè la versione del formato e oggi vale sempre1. - Il campo
idè univoco e stabile per evento, e il tuo gioco deve usarlo per ignorare i duplicati. - Il campo
typeègift,comment,like,follow,share,subscribe,joinoviewers. - Il campo
tsè l'ora dell'evento nel formato RFC 3339 UTC con millisecondi. - I campi
live_id,game_ideroom_ididentificano la live, il tuo gioco e la stanza di TikTok. - Il campo
testètruesolo negli eventi di prova. - L'oggetto
userdescrive lo spettatore ed ènullsolo negli eventiviewers. - Ogni evento porta soltanto l'oggetto del suo tipo (
gift,comment,like,viewersosubscribe) e gli altri sononull. - L'array
actionselenca ciò che il tuo gioco deve fare, ciascuna conaction_key,params,rule_iderepeat. - Il tuo gioco deve eseguire ogni azione tante volte quante indica
repeat, che vale 1 tranne nelle regole di un like ogni N.
Esempi degli otto tipi di evento
gift
{
"v": 1,
"id": "tt:7421000000000001001",
"type": "gift",
"ts": "2026-10-03T18:05:12.345Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": {
"gift_id": "5655",
"name": "Rose",
"image_url": "https://p16-webcast.tiktokcdn.com/img/maliva/webcast-va/eba3a9bb85c33e017f3648eaf88d7189-tplv-obj.webp",
"roblox_image_id": null,
"count": 2,
"diamonds_unit": 1,
"diamonds_total": 2,
"streakable": true,
"streak": {
"streak_id": "7421000000000000777",
"total": 3,
"ended": false
}
},
"comment": null,
"like": null,
"viewers": null,
"subscribe": null,
"actions": [
{
"action_key": "show_message",
"params": {
"text": "Ana envió 3 Rose",
"color": "#FF3B5C"
},
"rule_id": "rose-message",
"repeat": 1
}
]
}comment
{
"v": 1,
"id": "tt:7421000000000001002",
"type": "comment",
"ts": "2026-10-03T18:05:13.100Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": null,
"comment": {
"text": "!spawn 2 por favor"
},
"like": null,
"viewers": null,
"subscribe": null,
"actions": [
{
"action_key": "spawn_item",
"params": {
"count": 1
},
"rule_id": "spawn-command",
"repeat": 1
},
{
"action_key": "show_message",
"params": {
"text": "Ana usó !spawn",
"color": "#22C55E"
},
"rule_id": "spawn-command",
"repeat": 1
}
]
}like
{
"v": 1,
"id": "tt:7421000000000001003",
"type": "like",
"ts": "2026-10-03T18:05:14.020Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": null,
"comment": null,
"like": {
"count": 15,
"total": 1200
},
"viewers": null,
"subscribe": null,
"actions": [
{
"action_key": "spawn_item",
"params": {
"count": 5
},
"rule_id": "likes-100",
"repeat": 1
}
]
}follow
{
"v": 1,
"id": "tt:7421000000000001004",
"type": "follow",
"ts": "2026-10-03T18:05:15.500Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": null,
"comment": null,
"like": null,
"viewers": null,
"subscribe": null,
"actions": [
{
"action_key": "show_message",
"params": {
"text": "¡Gracias por seguir, Ana!",
"color": "#3B82F6"
},
"rule_id": "follow-thanks",
"repeat": 1
}
]
}share
{
"v": 1,
"id": "tt:7421000000000001005",
"type": "share",
"ts": "2026-10-03T18:05:16.250Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": false,
"follower": true,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 3
}
},
"gift": null,
"comment": null,
"like": null,
"viewers": null,
"subscribe": null,
"actions": []
}subscribe
{
"v": 1,
"id": "tt:7421000000000001006",
"type": "subscribe",
"ts": "2026-10-03T18:05:17.000Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000001",
"unique_id": "ana_streams",
"nickname": "Ana",
"avatar_url": "https://p16-sign-va.tiktokcdn.com/tos-maliva-avt-0068/7310000000000000001-tplv-tiktokx-cropcenter:100:100.webp",
"badges": {
"moderator": false,
"subscriber": true,
"follower": true,
"top_gifter": false,
"fan_club_level": 4,
"gifter_level": 3
}
},
"gift": null,
"comment": null,
"like": null,
"viewers": null,
"subscribe": {
"months": 3
},
"actions": []
}join
{
"v": 1,
"id": "tt:7421000000000001007",
"type": "join",
"ts": "2026-10-03T18:05:18.750Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": {
"user_id": "6800000000000000002",
"unique_id": "beto",
"nickname": "Beto",
"avatar_url": "https://api.tikaresv.com/v1/media/avatars/default.png",
"badges": {
"moderator": false,
"subscriber": false,
"follower": false,
"top_gifter": false,
"fan_club_level": 0,
"gifter_level": 0
}
},
"gift": null,
"comment": null,
"like": null,
"viewers": null,
"subscribe": null,
"actions": []
}viewers
{
"v": 1,
"id": "ag:01928f3d-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
"type": "viewers",
"ts": "2026-10-03T18:05:20.000Z",
"live_id": "01928f3a-7b2c-7d4e-8f90-a1b2c3d4e5f6",
"game_id": "0b7e5c1a-3d2f-4a6b-8c9e-1f2a3b4c5d6e",
"room_id": "7421000000000000001",
"test": false,
"user": null,
"gift": null,
"comment": null,
"like": null,
"viewers": {
"current": 1234,
"total_unique": 5678
},
"subscribe": null,
"actions": []
}Questi sono gli otto tipi di evento con un esempio reale di ciascuno.
| Variabile | Origine |
|---|---|
{{nickname}} | user.nickname |
{{unique_id}} | user.unique_id |
{{gift_name}} | gift.name |
{{gift_count}} | gift.count |
{{diamonds}} | gift.diamonds_total |
{{comment}} | comment.text |
{{likes}} | like.total |
I testi di params arrivano già con le variabili sostituite, e nessuno supera i 500 caratteri.
Cursore e ripresa
Il cursore è un indicatore opaco che segna fino a quale evento è arrivato il tuo gioco, e serve a non perdere eventi se la connessione si interrompe.
1791062100000-42- Conserva il cursore di ogni messaggio
evento di ogni risposta di richiesta. - Alla riconnessione invia l'ultimo cursore conservato per ricevere ciò che ti sei perso.
- Senza cursore, ricevi solo gli eventi successivi alla connessione.
- Se il campo
resetarriva atrue, l'app è stata riavviata o il cursore non è più disponibile, e riceverai solo eventi nuovi.
Il cursore avanza anche sugli eventi che il tuo filtro di tipi scarta, quindi non li riceverai più.
Errori
Tutti gli errori HTTP hanno la stessa forma, con un code stabile che puoi confrontare nel tuo codice e un message in inglese.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }| Codice | HTTP | Motivo | Cosa fare |
|---|---|---|---|
ORIGIN_FORBIDDEN | 403 | host_not_loopback | Collegati sempre a `127.0.0.1` o `localhost` e non usare un altro nome di host. |
LOCAL_KEY_INVALID | 401 | key_missing | Invia la API key nell'URL del WebSocket o nell'intestazione `x-api-key`. |
LOCAL_KEY_INVALID | 401 | key_format | Verifica che la key abbia il formato `tkv_live_` seguito da 32 caratteri alfanumerici. |
LOCAL_KEY_INVALID | 401 | key_unknown | Verifica di usare la key vigente del tuo gioco e chiedi al team una nuova key se l'hai persa. |
LOCAL_KEY_INVALID | 401 | game_inactive | Il tuo gioco è disattivato, quindi contatta il team di TikAresV. |
LOCAL_KEY_INVALID | 401 | game_not_visible | Il tuo gioco non è disponibile per questo streamer, quindi contatta il team di TikAresV. |
LOCAL_KEY_INVALID | 401 | unresolved_offline | L'app non ha potuto validare la key per mancanza di internet o per troppi tentativi, quindi attendi qualche secondo e riprova. |
LOCAL_ACCESS_EXPIRED | 403 | no_valid_token | Il piano dello streamer non è valido, quindi deve rinnovarlo nella sezione Piano dell'app e il tuo gioco deve riprovare ogni 30 secondi. |
LOCAL_GAMES_LIMIT | 403 | È stato raggiunto il massimo di giochi collegati del piano, quindi chiudi un altro gioco o chiedi allo streamer un piano con più giochi. | |
LOCAL_CURSOR_RESET | 200 | Non è un errore HTTP, ma l'avviso che l'app è stata riavviata, e il tuo gioco prosegue con i nuovi eventi. | |
COMMON_VALIDATION_FAILED | 422 | Controlla `details.fields` per vedere quale parametro non è valido e correggilo. | |
COMMON_NOT_FOUND | 404 | Controlla la rotta, oppure attendi che l'app scarichi la configurazione del gioco se hai richiesto `/v1/config`. | |
COMMON_INTERNAL | 500 | È un errore imprevisto dell'app, quindi riprova con attesa crescente e avvisa il team se persiste. |
La tabella indica cosa fare per ogni errore.
Codici di chiusura del WebSocket
Quando la connessione si chiude, il codice indica cosa deve fare il tuo gioco.
| Codice | Motivo |
|---|---|
1000 | normal |
1001 | going_away |
1008 | too_slow |
1009 | message_too_big |
4401 | key_invalid |
4403 | access_expired |
4408 | pong_timeout |
- Il codice 1000 significa che il tuo gioco ha chiuso la connessione, e non richiede azioni.
- Il codice 1001 significa che l'app si è chiusa o ha cambiato porta, e il tuo gioco deve riconnettersi con attesa crescente e l'ultimo cursore.
- Il codice 1008 significa che il tuo gioco è troppo lento, e deve riconnettersi con l'ultimo cursore.
- Il codice 1009 significa che il tuo gioco ha inviato un messaggio troppo grande, e devi correggere il client.
- Il codice 4401 significa che la key non è valida o è stata revocata, e il tuo gioco non deve riconnettersi finché non la cambia.
- Il codice 4403 significa che l'accesso è scaduto, e il tuo gioco deve interrogare
/v1/statusogni 30 secondi finchéservingnon ètrue. - Il codice 4408 significa che il tuo gioco non ha risposto al
pongin tempo, e deve riconnettersi con attesa crescente e l'ultimo cursore.
Limiti e valori fissi
Questi sono i limiti applicati dalla API locale, e gli identificatori C-### sono i nomi interni di ciascun valore.
| Costante | Valore | Descrizione |
|---|---|---|
C-020 | 17920 | Porta predefinita della API locale. |
C-021 | 25 | Attesa massima in secondi di una richiesta periodica e timeout consigliato per il client. |
C-022 | 10000 | Eventi conservati per gioco, o quelli degli ultimi 10 minuti. |
C-026 | 30 | Secondi tra un ping e l'altro del WebSocket. |
C-027 | 10 | Secondi a disposizione del tuo gioco per rispondere al pong. |
C-028 | 1, 2, 4, 8, 16, 30 | Attesa in secondi tra le riconnessioni, con una variazione casuale del 20 %. |
C-034 | 65536 | Dimensione massima in byte di un messaggio del WebSocket. |
C-050 | 60 | Secondi senza richieste prima che l'app consideri il gioco disconnesso. |
C-057 | 100 | Eventi massimi per risposta di una richiesta periodica. |
C-137 | 86400 | Secondi per cui una API key resta valida dopo essere stata ruotata. |
C-138 | tkv_live_ + 32 base62 | Formato della API key. |
C-141 | 3 | Giochi collegati contemporaneamente per impostazione predefinita. |
C-155 | 500 | Lunghezza massima in caratteri di un testo con variabili. |
Avviso di rete locale in Chrome
Quando una pagina pubblica si collega a 127.0.0.1, Chrome mostra un avviso di autorizzazione per l'accesso alla rete locale.
Lo streamer deve accettare quell'avviso una volta, altrimenti il browser bloccherà la connessione del tuo gioco con l'app.
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: x-api-key, if-none-match
Access-Control-Allow-Private-Network: true
Access-Control-Max-Age: 600- L'avviso compare solo nelle pagine pubbliche, e una pagina aperta da un file locale o da
http://127.0.0.1non lo mostra. - Se lo streamer ha rifiutato l'autorizzazione, deve abilitarla nelle impostazioni del sito in Chrome e ricaricare la pagina.
- Usa sempre
127.0.0.1al posto dilocalhost, perché il sistema può risolverelocalhostprima in::1e l'app non è in ascolto lì.
Come provare il tuo gioco
Per provare senza aspettare un regalo reale, lo streamer può inviare eventi di prova dall'app.
- Apri l'app desktop di TikAresV e accedi.
- Entra nel gioco dall'elenco dei giochi dell'app.
- Apri una regola esistente o creane una nuova nell'editor delle regole.
- Premi il pulsante Prova dell'editor delle regole.
- Verifica che il tuo gioco riceva l'evento ed esegua l'azione.
Gli eventi di prova arrivano con test: true e con un id che inizia con test:.
GET http://127.0.0.1:17920/harnessL'app include inoltre una pagina di prova che mostra ciò che riceverebbe un gioco, senza bisogno di averne uno.
Risoluzione dei problemi
Controlla queste cause in ordine quando il tuo gioco non riceve eventi.
- Se la connessione fallisce subito, apri
http://127.0.0.1:17920/v1/statusnel browser e verifica che l'app risponda. - Se
localhostnon si collega, passa a127.0.0.1, perché l'app non è in ascolto su::1. - Se ricevi l'errore 401, verifica che la key abbia il formato
tkv_live_più 32 caratteri e che non sia stata ruotata. - Se ricevi l'errore 403 con
LOCAL_ACCESS_EXPIRED, chiedi allo streamer di rinnovare il piano nella sezione Piano dell'app. - Se ricevi l'errore 403 con
LOCAL_GAMES_LIMIT, chiudi un altro gioco collegato o chiedi allo streamer un piano con più giochi. - Se il browser blocca la connessione senza mostrare un errore dell'app, accetta l'avviso di rete locale di Chrome.
- Se la connessione cade ogni pochi secondi, verifica che il tuo gioco risponda
ponga ognipingin meno di 10 secondi. - Se vedi eventi ripetuti dopo aver riavviato l'app, ignora quelli già elaborati usando l'
iddell'evento. - Se vedi il campo
resetatrue, l'app è stata riavviata e il cursore precedente non è più valido, quindi il tuo gioco riceverà solo eventi nuovi.