Documentació per a jocs web
Connecta el teu joc del navegador amb els esdeveniments del directe de TikTok mitjançant l'aplicació d'escriptori de TikAresV.
Què és i com funciona
TikAresV és una aplicació d'escriptori que llegeix els esdeveniments del directe de TikTok de l'streamer (regals, comentaris, likes, seguidors, comparticions, subscripcions, entrades i espectadors) i els lliura al teu joc.
L'aplicació obre a l'ordinador de l'streamer una API local a 127.0.0.1, i el teu joc, que s'executa al navegador d'aquell mateix ordinador, s'hi connecta amb una API key.
- L'API local només existeix mentre l'aplicació d'escriptori és oberta a l'ordinador on s'executa el joc.
- Cada esdeveniment arriba amb un
idestable, de manera que el teu joc pot ignorar els que ja ha processat. - El streamer defineix a l'aplicació quina acció es dispara amb cada regal, comentari o like, i el teu joc només executa les accions que rep.
- Pots rebre els esdeveniments per WebSocket, que és el més còmode al navegador, o per consulta periòdica (long-poll) si prefereixes HTTP simple.
Per rebre esdeveniments només necessites l'API key del teu joc, un navegador a l'ordinador de l'streamer i les instruccions d'aquesta pàgina.
Alta del joc i API key
L'alta dels jocs la fa l'equip de TikAresV, així que escriu-nos per registrar el teu.
Contactar amb l'equip de TikAresVQuan el teu joc estigui registrat rebràs les dades següents.
- El
game_idés l'identificador únic del teu joc. - L'API key té la forma
tkv_live_més 32 caràcters alfanumèrics i es mostra una sola vegada, així que guarda-la de seguida. - El
game_guidnomés es lliura als jocs de Roblox.
tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxSi necessites canviar la key, l'equip en genera una de nova i l'anterior continua valent durant 24 hores (86400 segons) perquè actualitzis el teu joc sense talls.
Tracta la key com una contrasenya del teu joc i no la publiquis en repositoris oberts que no siguin teus.
Autenticació amb l'API key
Cada crida que lliura esdeveniments o configuració s'autentica amb l'API key del teu joc, que té la forma tkv_live_ seguida de 32 caràcters alfanumèrics.
| Ruta | Credencial |
|---|---|
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 viatja dins del codi del teu joc i l'identifica com a joc davant l'aplicació, així que no la comparteixis amb altres jocs.
- El WebSocket rep la key al paràmetre
keyde l'URL, perquè el navegador no permet posar capçaleres en un WebSocket. - Les rutes HTTP
/v1/events/polli/v1/configreben la key només a la capçalerax-api-key, i el paràmetrekeys'hi ignora. - La ruta
/v1/statusno necessita key, així que serveix per saber si l'aplicació és oberta abans de connectar.
Inici ràpid
Amb aquests passos el teu joc rep el primer esdeveniment en pocs minuts.
- Demana l'alta del teu joc a l'equip de TikAresV i guarda l'API key que rebis, perquè només es mostra una vegada.
- Demana a l'streamer que obri l'aplicació d'escriptori de TikAresV i iniciï sessió.
- Copia l'exemple d'aquesta secció en un fitxer
.htmli substitueix el marcador de l'API key per la teva. - Obre el fitxer al navegador del mateix ordinador on s'executa l'aplicació, i si Chrome pregunta per l'accés a la xarxa local, accepta.
- Demana a l'streamer que entri al seu joc a l'aplicació, que editi una regla i que premi el botó Provar.
- Comprova que el registre de la pàgina mostra una línia amb l'
idde l'esdeveniment de prova i el nom de l'acció. - Quan funcioni, substitueix la funció
runActionpel codi del teu joc per a cada acció.
<!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>
Si alguna cosa falla, revisa la taula d'errors i la secció de resolució de problemes més avall.
Estat de l'aplicació: GET /v1/status
Aquesta ruta indica si l'aplicació és oberta i si pot servir esdeveniments, i no necessita 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"
}- El camp
servingéstruequan l'aplicació pot lliurar esdeveniments al teu joc. - El camp
serving_reasonexplica per què serveix o per què no, ino_valid_tokenvol dir que el pla de l'streamer no és vigent. - El camp
tiktok_statevaldisconnectedsense captura,waitingesperant el directe istreamingamb el directe en curs. - Els camps
connected_gamesimax_connected_gamesindiquen quants jocs hi ha connectats i quants en permet el pla.
Connexió per WebSocket: GET /v1/events
El WebSocket lliura els esdeveniments tan bon punt arriben, i és la forma recomanada per a jocs web.
GET ws://127.0.0.1:17920/v1/events?key=tkv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&types=gift,comment&cursor=1791062100000-41- El paràmetre
keyés obligatori i porta l'API key codificada ambencodeURIComponent. - El paràmetre
typesés opcional, llista els tipus separats per comes sense espais, i si falta es reben els vuit tipus. - El paràmetre
cursorés opcional i reprèn el lliurament des de l'últim esdeveniment que el teu joc va processar.
Just després de connectar, l'aplicació envia un missatge hello amb l'estat de la sessió.
{
"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'aplicació envia un ping cada 30 segons i el teu joc ha de respondre pong amb el mateix ts dins de 10 segons, o l'aplicació tanca la connexió amb el codi 4408.
{ "type": "pong", "data": { "ts": 1791062130000 } }Consulta periòdica: GET /v1/events/poll
Aquesta ruta és l'alternativa als WebSocket per a clients que només saben fer peticions HTTP, i espera fins a wait segons abans de respondre buida.
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| Paràmetre | Obligatori | Per defecte | Rang |
|---|---|---|---|
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"
}- Repeteix la consulta tan bon punt rebis la resposta, enviant el
cursorde la resposta anterior. - El camp
has_moreéstruequan han quedat esdeveniments pel límitlimit, i llavors has de consultar de nou sense esperar. - Si deixes de consultar durant 60 segons, l'aplicació considera que el teu joc s'ha desconnectat.
Regles vigents: GET /v1/config
Aquesta ruta retorna les regles que l'streamer ha configurat per al teu joc, i serveix per mostrar ajudes en pantalla.
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", "…": "…" } ] } }El teu joc no necessita interpretar les regles, perquè cada esdeveniment ja porta les seves accions resoltes.
Contingut de cada esdeveniment
Cada esdeveniment té els mateixos camps comuns, i cada tipus afegeix el seu propi objecte amb les dades específiques.
{
"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 }
]
}- El camp
vés la versió del format i avui val sempre1. - El camp
idés únic i estable per esdeveniment, i el teu joc l'ha d'usar per ignorar duplicats. - El camp
typeésgift,comment,like,follow,share,subscribe,joinoviewers. - El camp
tsés l'hora de l'esdeveniment en format RFC 3339 UTC amb mil·lisegons. - Els camps
live_id,game_idiroom_ididentifiquen el directe, el teu joc i la sala de TikTok. - El camp
testéstruenomés en els esdeveniments de prova. - L'objecte
userdescriu l'espectador i ésnullnomés en els esdevenimentsviewers. - Cada esdeveniment porta únicament l'objecte del seu tipus (
gift,comment,like,viewersosubscribe) i els altres sónnull. - L'array
actionsllista el que el teu joc ha de fer, cadascuna ambaction_key,params,rule_idirepeat. - El teu joc ha d'executar cada acció tantes vegades com indiqui
repeat, que val 1 tret de les regles de cada N likes.
Exemples dels vuit tipus d'esdeveniment
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": []
}Aquests són els vuit tipus d'esdeveniment amb un exemple real de cadascun.
| Variable | Origen |
|---|---|
{{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 |
Els textos de params ja vénen amb les variables substituïdes, i cap no supera els 500 caràcters.
Cursor i represa
El cursor és una marca opaca que indica fins a quin esdeveniment ha arribat el teu joc, i serveix per no perdre esdeveniments si la connexió es talla.
1791062100000-42- Guarda el cursor de cada missatge
evento de cada resposta de consulta. - En reconnectar, envia l'últim cursor guardat per rebre el que t'has perdut.
- Sense cursor, només reps els esdeveniments posteriors a la connexió.
- Si el camp
resetarriba entrue, l'aplicació s'ha reiniciat o el cursor ja no està disponible, i només rebràs esdeveniments nous.
El cursor avança també sobre els esdeveniments que el teu filtre de tipus descarta, així que no els tornaràs a rebre.
Errors
Tots els errors HTTP tenen la mateixa forma, amb un code estable que pots comparar al teu codi i un message en anglès.
{ "error": { "code": "LOCAL_KEY_INVALID", "message": "local api key invalid", "details": { "reason": "key_format" } } }| Codi | HTTP | Motiu | Què cal fer |
|---|---|---|---|
ORIGIN_FORBIDDEN | 403 | host_not_loopback | Connecta't sempre a `127.0.0.1` o `localhost` i no facis servir cap altre nom d'equip. |
LOCAL_KEY_INVALID | 401 | key_missing | Envia l'API key a l'URL del WebSocket o a la capçalera `x-api-key`. |
LOCAL_KEY_INVALID | 401 | key_format | Revisa que la key tingui el format `tkv_live_` seguit de 32 caràcters alfanumèrics. |
LOCAL_KEY_INVALID | 401 | key_unknown | Comprova que fas servir la key vigent del teu joc i demana'n una de nova a l'equip si l'has perdut. |
LOCAL_KEY_INVALID | 401 | game_inactive | El teu joc està desactivat, així que contacta amb l'equip de TikAresV. |
LOCAL_KEY_INVALID | 401 | game_not_visible | El teu joc no està disponible per a aquest streamer, així que contacta amb l'equip de TikAresV. |
LOCAL_KEY_INVALID | 401 | unresolved_offline | L'aplicació no ha pogut validar la key per manca d'internet o per massa intents, així que espera uns segons i reintenta. |
LOCAL_ACCESS_EXPIRED | 403 | no_valid_token | El pla de l'streamer no és vigent, així que l'ha de renovar a la secció Pla de l'aplicació i el teu joc ha de reintentar cada 30 segons. |
LOCAL_GAMES_LIMIT | 403 | S'ha arribat al màxim de jocs connectats del pla, així que tanca un altre joc o demana a l'streamer un pla amb més jocs. | |
LOCAL_CURSOR_RESET | 200 | No és un error HTTP, sinó l'avís que l'aplicació s'ha reiniciat, i el teu joc continua amb els esdeveniments nous. | |
COMMON_VALIDATION_FAILED | 422 | Revisa `details.fields` per veure quin paràmetre no és vàlid i corregeix-lo. | |
COMMON_NOT_FOUND | 404 | Revisa la ruta, o espera que l'aplicació baixi la configuració del joc si has demanat `/v1/config`. | |
COMMON_INTERNAL | 500 | És un error inesperat de l'aplicació, així que reintenta amb espera creixent i avisa l'equip si persisteix. |
La taula indica què cal fer davant de cada error.
Codis de tancament del WebSocket
Quan la connexió es tanca, el codi indica què ha de fer el teu joc.
| Codi | Motiu |
|---|---|
1000 | normal |
1001 | going_away |
1008 | too_slow |
1009 | message_too_big |
4401 | key_invalid |
4403 | access_expired |
4408 | pong_timeout |
- El codi 1000 vol dir que el teu joc ha tancat la connexió, i no requereix cap acció.
- El codi 1001 vol dir que l'aplicació s'ha tancat o ha canviat de port, i el teu joc s'ha de reconnectar amb espera creixent i l'últim cursor.
- El codi 1008 vol dir que el teu joc és massa lent, i s'ha de reconnectar amb l'últim cursor.
- El codi 1009 vol dir que el teu joc ha enviat un missatge massa gran, i has de corregir el client.
- El codi 4401 vol dir que la key no és vàlida o ha estat revocada, i el teu joc no s'ha de reconnectar fins a canviar-la.
- El codi 4403 vol dir que l'accés ha vençut, i el teu joc ha de consultar
/v1/statuscada 30 segons fins queservingsiguitrue. - El codi 4408 vol dir que el teu joc no ha respost el
ponga temps, i s'ha de reconnectar amb espera creixent i l'últim cursor.
Límits i valors fixos
Aquests són els límits que aplica l'API local, i els identificadors C-### són els noms interns de cada valor.
| Constant | Valor | Descripció |
|---|---|---|
C-020 | 17920 | Port per defecte de l'API local. |
C-021 | 25 | Espera màxima en segons d'una consulta periòdica i temps límit recomanat per al client. |
C-022 | 10000 | Esdeveniments retinguts per joc, o els dels últims 10 minuts. |
C-026 | 30 | Segons entre cada ping del WebSocket. |
C-027 | 10 | Segons que té el teu joc per respondre el pong. |
C-028 | 1, 2, 4, 8, 16, 30 | Espera en segons entre reconnexions, amb una variació aleatòria del 20 %. |
C-034 | 65536 | Mida màxima en bytes d'un missatge del WebSocket. |
C-050 | 60 | Segons sense consultar perquè l'aplicació consideri el joc desconnectat. |
C-057 | 100 | Esdeveniments màxims per resposta d'una consulta periòdica. |
C-137 | 86400 | Segons que continua valent una API key després de ser rotada. |
C-138 | tkv_live_ + 32 base62 | Format de l'API key. |
C-141 | 3 | Jocs connectats alhora per defecte. |
C-155 | 500 | Llargada màxima en caràcters d'un text amb variables. |
Avís de xarxa local a Chrome
Quan una pàgina pública es connecta a 127.0.0.1, Chrome mostra un avís de permís d'accés a la xarxa local.
El streamer ha d'acceptar aquest avís una vegada, o el navegador bloquejarà la connexió del teu joc amb l'aplicació.
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'avís apareix només en pàgines públiques, i una pàgina oberta des d'un fitxer local o des de
http://127.0.0.1no el mostra. - Si l'streamer ha rebutjat el permís, l'ha d'habilitar a la configuració del lloc a Chrome i recarregar la pàgina.
- Fes servir sempre
127.0.0.1en lloc delocalhost, perquè el sistema pot resoldrelocalhostprimer a::1i l'aplicació no hi escolta.
Com provar el teu joc
Per provar sense esperar un regal real, l'streamer pot enviar esdeveniments de prova des de l'aplicació.
- Obre l'aplicació d'escriptori de TikAresV i inicia sessió.
- Entra al joc a la llista de jocs de l'aplicació.
- Obre una regla existent o crea'n una de nova a l'editor de regles.
- Prem el botó Provar de l'editor de regles.
- Comprova que el teu joc rep l'esdeveniment i executa l'acció.
Els esdeveniments de prova arriben amb test: true i amb un id que comença per test:.
GET http://127.0.0.1:17920/harnessL'aplicació inclou a més una pàgina de proves que mostra el que rebria un joc, sense necessitat de tenir-ne un.
Resolució de problemes
Revisa aquestes causes per ordre quan el teu joc no rebi esdeveniments.
- Si la connexió falla de seguida, obre
http://127.0.0.1:17920/v1/statusal navegador i comprova que l'aplicació respon. - Si
localhostno connecta, canvia a127.0.0.1, perquè l'aplicació no escolta a::1. - Si reps l'error 401, revisa que la key tingui el format
tkv_live_més 32 caràcters i que no hagi estat rotada. - Si reps l'error 403 amb
LOCAL_ACCESS_EXPIRED, demana a l'streamer que renovi el seu pla a la secció Pla de l'aplicació. - Si reps l'error 403 amb
LOCAL_GAMES_LIMIT, tanca un altre joc connectat o demana a l'streamer un pla amb més jocs. - Si el navegador bloqueja la connexió sense mostrar un error de l'aplicació, accepta l'avís de xarxa local de Chrome.
- Si la connexió cau cada pocs segons, comprova que el teu joc respon
ponga cadapingen menys de 10 segons. - Si veus esdeveniments repetits després de reiniciar l'aplicació, ignora els que ja has processat fent servir l'
idde l'esdeveniment. - Si veus el camp
resetentrue, l'aplicació s'ha reiniciat i el cursor anterior ja no serveix, així que el teu joc només rebrà esdeveniments nous.