Guia de integração do plicflix

Para estúdios de jogos. Este guia explica tudo o que é preciso para pôr um jogo no plicflix: o jogador entra sem login, a tela de carregamento do plicflix acompanha o jogo, a bolha do plicflix fica por cima dele, o jogador sai sem perder o progresso e os amigos se encontram dentro do jogo.

SDK atual: plicflix.js 2.3.0.

É uma IA fazendo a integração? Comece por COMECE: é o passo a passo completo, com os endereços de cada ambiente e o exemplo pronto para baixar. A lista de tudo, em texto puro: https://developers.plicflix.com/llms.txt.

Sumário

1. Como funciona
2. Antes de começar: o cadastro
3. Começo rápido
4. Entrada: o jogador já chega logado
5. Deixar o plicflix abrir o seu jogo
6. A tela de carregamento
7. A bolha do plicflix
8. Sair salvando
9. Onde o jogador está
10. Amigos: "Ir até" e "Chamar para cá"
11. Referência do SDK
12. O protocolo de mensagens (sem o SDK em JavaScript)
13. A API do plicflix para o seu servidor
14. Unity, Godot, jogos sem servidor e outros motores
15. Segurança
16. Testar antes de publicar
17. Lista de conferência
18. Versões do SDK

1. Como funciona

 app plicflix ──(1) toque em Jogar──▶ API plicflix: abre a partida e cria um TOKEN de uso único
      │
      │ (2) abre o SEU jogo, no SEU servidor, POR CIMA do app (iframe na web, WebView no celular),
      ▼     com a tela de carregamento do plicflix na frente:
            https://seu-jogo.com/?ref=plicflix#plicflix=pft_…&pf_idioma=pt-BR&pf_plataforma=web
 seu jogo (navegador) ──(3) Plicflix.entrar("/api/plicflix/entrar")──▶ SEU servidor
                                                                        │ (4) POST /v1/ingresso/trocar
                                                                        │     Authorization: Bearer pk_…
                                                                        ▼
                                                    API plicflix ──▶ { jogador: { id, nome }, contexto }
 seu jogo ◀──(5) sessão criada (cookie) ────────────────────────────────┘
      │
      ├──(6) Plicflix.progresso() / Plicflix.pronto() ──▶ a tela de carregamento acompanha e sai
      ├──(7) Plicflix.onde({ texto, area, ponto }) ────▶ o plicflix sabe onde o jogador está
      ├──(8) Plicflix.aoSair(salvar) ◀─── "Sair do jogo" na bolha (o app espera você salvar)
      └──(9) Plicflix.aoIrPara(levar) ◀── um amigo quer vir até aqui (você leva o jogador até ele)

O que é de cada um:

Só dois dados do jogador chegam ao seu jogo:

E-mail, dados de pagamento e país nunca chegam ao jogo.

2. Antes de começar: o cadastro

Tudo começa no plicflix developers (https://developers.plicflix.com). O caminho inteiro, passo a passo, está em COMECE. Em resumo:

1. crie a conta (você e o estúdio) e pague a fatura da taxa de entrada, que aparece na sua área;
2. gere a chave de integração (pk_…). Ela aparece uma vez e é secreta: fica só no seu servidor, nunca no navegador;
3. cadastre o jogo. Ele nasce não publicado: só os testadores que você indicar veem, na fileira "Em teste" do app;
4. monte a vitrine e envie as imagens e o trailer (com a qualidade mínima, veja VITRINE);
5. com a lista de conferência toda verde, envie para revisão. A equipe plicflix testa e publica.

O que você informa ao cadastrar o jogo:

Depois de cadastrado, a vitrine é editada no painel (ou por PUT /v1/parceiro/jogos/{slug}, veja API).

A vigia marca o jogo assim:

• online: respondeu 2xx/3xx, ou 401/403, em menos de 2,5 s;
• instável: respondeu em mais de 2,5 s, ou falhou uma vez;
• fora do ar: falhou 2 vezes seguidas.

Com o jogo fora do ar, o app mostra "Fora do ar" e não deixa abrir (só os testadores de um jogo não publicado conseguem abrir mesmo assim). Endereços localhost não são vigiados.

3. Começo rápido

O mínimo para o jogador entrar logado, com a tela de carregamento e o sair salvando:

No navegador — dois arquivos, sem script inline (assim a sua CSP pode ser script-src 'self'):

<!-- index.html -->
<script src="/plicflix.js"></script>          <!-- cópia de https://developers.plicflix.com/sdk/plicflix.js, sem mudar nada -->
<script type="module" src="/jogo.js"></script>

// jogo.js (um módulo: pode usar await)
if (Plicflix.dentro()) {
  Plicflix.progresso(10, "Entrando…");
  try {
    await Plicflix.entrar("/api/plicflix/entrar");   // o SEU servidor troca o token e cria a sessão
  } catch (e) {
    // não deu (token vencido, ou recarregou depois de entrar): use a sessão que já existe
    // ou mostre o seu login de sempre
  }
  Plicflix.aoSair(() => salvarProgresso());          // o "Sair" da bolha espera você salvar
}
// … carregue o jogo …
Plicflix.pronto();                                   // tira a tela de carregamento do plicflix

No servidor (Node, com Express):

import express from "express";
import { trocarIngresso } from "./plicflix.mjs";   // https://developers.plicflix.com/sdk/plicflix.mjs?baixar=1

const app = express();
app.use(express.json());

app.post("/api/plicflix/entrar", async (req, res) => {
  let r;
  try {
    r = await trocarIngresso(req.body.token);        // lê PLICFLIX_CHAVE e PLICFLIX_API do ambiente
  } catch (e) {
    return res.status(e.status === 401 ? 401 : 502).json({ erro: "abra o jogo de novo pelo plicflix" });
  }
  if (r.jogo !== "meu-jogo") return res.status(401).end();     // o seu slug
  // ache ou crie a conta pelo r.jogador.id ("pf_…", fixo) e guarde o r.jogador.nome
  const conta = await suaFuncaoAcharOuCriarConta(r.jogador.id, r.jogador.nome);
  const sessao = await suaFuncaoCriarSessao(conta);
  // o cookie do iframe (escrito à mão: a opção "partitioned" do res.cookie só existe no Express 5)
  res.setHeader("Set-Cookie", `sessao=${sessao}; Path=/; HttpOnly; Secure; SameSite=None; Partitioned; Max-Age=2592000`);
  res.json({ ok: true });
});

Exemplo completo e executável (Node sem dependências, ou Go): baixe exemplo-node.zip ou exemplo-go.zip. Rode com PLICFLIX_CHAVE=pk_… node server.mjs e siga o README de dentro.

E a permissão para o plicflix abrir o jogo, que é o passo 5.

Com isso o jogo já funciona no plicflix. Os passos 9 e 10 (onde o jogador está, amigos) deixam a experiência completa.

4. Entrada: o jogador já chega logado

O que chega no endereço

O app abre https://seu-jogo/?ref=plicflix#plicflix=pft_…&pf_idioma=pt-BR&pf_plataforma=android.

• ?ref=plicflix: vai para o seu servidor. Use nas suas métricas.
• O fragmento (#…): o navegador nunca envia ao seu servidor, então o token não aparece nos seus logs. O SDK lê o token e apaga o fragmento da barra de endereço.

O token

• Formato: pft_ seguido de 43 caracteres. É opaco: não carrega dado nenhum.
• Validade: 5 minutos ou uma troca, o que vier primeiro.
• Recarregar a página: antes da troca, o SDK guarda o token no sessionStorage da aba. Depois da troca, Plicflix.token() vem null e o jogador segue com a sua sessão. Plicflix.dentro() continua true, por causa do ?ref=plicflix.

A troca, no seu servidor

POST https://api.plicflix.com/v1/ingresso/trocar
Authorization: Bearer pk_…
Content-Type: application/json

{ "token": "pft_…" }

200:

{ "jogador": { "id": "pf_…", "nome": "Paulo" }, "jogo": "seu-slug", "partida": "pt_…",
  "assinante": true, "contexto": { "ref": "plicflix", "idioma": "pt-BR", "plataforma": "web" } }

401: o token é inválido, venceu, já foi trocado ou é de um jogo de outro parceiro. É sempre a mesma resposta, de propósito, para não ajudar quem tenta adivinhar tokens.

Os ajudantes já prontos (só a biblioteca padrão; leem PLICFLIX_CHAVE e PLICFLIX_API do ambiente):

• Node 18+: plicflix.mjs → await trocarIngresso(token);
• Go: plicflix.go → plicflix.DoAmbiente().Trocar(ctx, token).

Outra linguagem? É um POST comum, como acima. Erros: 401 (token ruim, de propósito sem detalhe), 400 (corpo inválido), 429 (limite), 5xx (tente de novo).

A conta

• Chave: ligue a conta do seu jogo a jogador.id, numa coluna única (por exemplo contas.plicflix_id).
• Sem senha utilizável: quem entra pelo plicflix não precisa de senha. Gere uma senha aleatória que ninguém conhece.
• Reserve o login interno: se o login for um e-mail, use um domínio que ninguém consiga cadastrar (por exemplo pf_…@plicflix.invalid) e recuse esse domínio no seu cadastro normal. Sem isso, alguém poderia criar a conta antes e tomar o lugar do jogador.
• O apelido muda: atualize o nome a cada entrada.
• Confira o jogo: confira jogo == seu slug antes de abrir a sessão.

5. Deixar o plicflix abrir o seu jogo

Na web, o app abre o jogo num <iframe>, num site diferente do seu. Duas coisas precisam estar certas.

a) Permitir o iframe. Tire o X-Frame-Options: DENY e liste as origens do plicflix na CSP:

Content-Security-Policy: …; frame-ancestors 'self' https://plicflix.com

As origens do plicflix (o que vai no frame-ancestors):

É só essa: www.plicflix.com e app.plicflix.com redirecionam para ela. O verificador ("Conferir agora" no painel) confere exatamente isso.

b) O cookie da sessão. Dentro de um iframe de outro site, o navegador não envia cookie SameSite=Strict nem Lax. Para a sessão criada pelo plicflix, use:

Set-Cookie: sessao=…; Path=/; HttpOnly; Secure; SameSite=None; Partitioned

• Por que Partitioned: o cookie fica guardado só para "o seu jogo dentro do plicflix". Nenhum outro site o recebe.
• Ao sair da conta, apague os dois cookies: o normal e o Partitioned.
• No celular, a WebView do app abre o jogo como página principal, então o cookie normal também funciona. Mesmo assim, use o mesmo código.
• Safari no computador: pode recusar cookies de outro site. Teste nele. Se o seu jogo não depender de cookie (por exemplo, guarda a sessão em memória e manda num cabeçalho), melhor ainda.
• localhost em teste: os navegadores aceitam Secure em http://localhost, então o mesmo cookie funciona no teste local.

6. A tela de carregamento

Do toque em "Jogar" até o jogo dizer que está pronto, a tela do plicflix fica por cima. Ela mostra o banner e o logo do seu jogo, a barra e os textos.

Chame pronto() assim que o jogador puder jogar. O tempo até o "pronto", ou a falha, chega ao estúdio.

7. A bolha do plicflix

Por cima de todo jogo, o app mostra a bolha do plicflix:

• é um botão redondo que o jogador arrasta para onde quiser (a posição fica guardada);
• o tamanho depende do aparelho: 56 px no celular, 64 no tablet, 46 no computador;
• parada, ela fica semitransparente.

O que ela mostra:

• avisos do plicflix (com número de não lidos e um balão);
• o tempo jogado e onde o jogador está;
• os amigos jogando agora, com "Ir até" e "Chamar".

O menu dela: Sair do jogo, Recarregar, Tela cheia (na web) e Reclamar.

O que isso significa para o seu jogo:

• Ela sempre fica por cima. O jogador pode movê-la, mas não deixe nada que só funcione num canto fixo da tela.
• Você não precisa fazer nada para ela aparecer. Ela é do app, não do seu jogo.
• Para abrir a lista de amigos da bolha, por exemplo num botão "Chamar amigos" do seu jogo, use Plicflix.abrirAmigos().

8. Sair salvando

Quando o jogador toca em Sair do jogo na bolha, ou no botão voltar do celular ou do navegador:

app  → jogo   { tipo: "saindo" }   o SDK chama a sua função de Plicflix.aoSair
jogo → app    { tipo: "saiu" }     o SDK responde sozinho quando a função termina
app           mostra "Salvando seu progresso…" e fecha. Sem resposta em 5 s, fecha assim mesmo.

Plicflix.aoSair(async () => {
  await salvarProgresso();   // ou: fechar a conexão do jogo direito, para o servidor gravar
});

• Se o seu servidor já salva o tempo todo, feche a conexão direito e espere o "fechou".
• Plicflix.sair() serve para o jogo fechar a si mesmo, por exemplo num botão "Voltar ao plicflix" dentro do jogo, depois de ter salvo.

9. Onde o jogador está

Conte ao plicflix onde o jogador está sempre que ele mudar de lugar:

Plicflix.onde({
  texto: "Taverna do Porto",                    // o que as pessoas leem: até 60 letras
  area:  "cidade/taverna",                       // para agrupar: minúsculas, números e / _ . -  (até 60)
  ponto: { cena: "taverna:1", x: 12, y: 8 },     // só o SEU jogo entende: objeto JSON de até 1 KB
});
Plicflix.onde("Fase 3");                         // também vale só o texto

O que o plicflix faz com isso:

E ainda:

• Continuar de onde parou: o último "onde" de cada jogo aparece na fileira "Continuar jogando" da tela inicial ("📍 Taverna do Porto · há 2 h"), em qualquer aparelho. O progresso continua sendo do seu jogo; o plicflix guarda só o marcador.
• Sem repetição: o mesmo "onde" seguido não é reenviado, e o app manda no máximo um a cada 1,5 s. Pode chamar à vontade.
• Privacidade: cada jogador escolhe quem vê onde ele está (amigos, todos ou ninguém). Veja SOCIAL.

Exemplo: a cada troca de cena, mande o nome do lugar, uma área (cidade, interior/casa, batalha) e { cena }.

10. Amigos: "Ir até" e "Chamar para cá"

Os jogadores do plicflix têm amigos, adicionados pelo código de amigo (8 letras, por exemplo 84A621CA). Na bolha e na tela Amigos aparece onde cada um está. Daí vêm dois botões:

• Ir até: abre o jogo do amigo, se ainda não for o mesmo, e pede ao jogo para levar o jogador até ele.
• Chamar para cá: o amigo recebe um aviso na bolha, com o botão "Ir". Isso libera o "ir até" por 24 h, mesmo que a privacidade de quem chamou esteja fechada.

O que o seu jogo recebe

Plicflix.aoIrPara(async (destino) => {
  // destino = {
  //   jogador_id: "pf_…",          o código de QUEM ESTÁ LÁ, no SEU jogo (o mesmo id da troca do token)
  //   jogador: "Ana",              o apelido
  //   texto: "Taverna do Porto", area: "cidade/taverna",
  //   ponto: { cena: "taverna:1", x: 12, y: 8 },   o que você mesmo mandou em Plicflix.onde (pode faltar)
  //   jogo: "seu-slug"
  // }
  const r = await fetch("/api/plicflix/ir", {
    method: "POST", credentials: "same-origin",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ jogador_id: destino.jogador_id }),
  }).then((x) => x.json());
  return { ok: r.ok, motivo: r.motivo };   // o motivo aparece para o jogador
});

O que devolver:

• true ou { ok: true }: o app mostra "Você foi até Ana.";
• false ou { ok: false, motivo: "Ela está numa terra particular." }: o app mostra o motivo.

A função pode devolver uma Promise. Se o jogo não registrar aoIrPara, o SDK responde sozinho "Este jogo ainda não sabe levar você até outra pessoa".

A regra de segurança mais importante

Nunca teletransporte o jogador pelo ponto vindo do navegador. Um trapaceiro manda qualquer coordenada. Mande o jogador_id para o seu servidor, ache lá o jogador online com esse código e leve até a posição real dele. Assim só dá para ir até alguém que está de fato no jogo.

O seu servidor também decide se pode:

• lugares privados, como a casa ou a terra de outro jogador;
• batalhas, partidas ranqueadas e instâncias cheias;
• um intervalo entre um "ir até" e outro.

O motivo de cada recusa volta para o jogador.

Quando chega o pedido

• Com o jogo aberto: o jogador está jogando e toca em "Ir até" na bolha. A mensagem chega na hora.
• Abrindo o jogo: o jogador estava fora e tocou em "Ir até" na tela Amigos. A mensagem chega logo depois do seu Plicflix.pronto().
  • Se o jogador ainda não estiver "no mundo", por exemplo criando o personagem, espere ele entrar e só então leve (o aoIrPara pode demorar: a Promise pode esperar alguns minutos).
• Amigo noutro jogo: se o amigo está em outro jogo, o app pergunta se o jogador quer sair deste. O seu aoSair roda normalmente, e o app abre o outro jogo.

11. Referência do SDK

Como distribuir o SDK:

• Copie plicflix.js para o seu site sem mudar nada. Assim ele passa pela sua CSP script-src 'self'.
• Tipos TypeScript: plicflix.d.ts.
• Ou carregue da CDN (https://sdk.plicflix.com/plicflix.js). Nesse caso, libere essa origem no script-src.

O SDK não tem dependências e funciona igual no iframe (web) e na WebView (celular).

12. O protocolo de mensagens (sem o SDK em JavaScript)

O SDK é só uma camada fina sobre mensagens. Um jogo que não roda JavaScript puro (um motor que expõe pontes, por exemplo) pode falar o protocolo direto. Toda mensagem do jogo leva v: 2.

Os canais

O app só aceita mensagens vindas da origem do seu jogo (a da url cadastrada).

As mensagens

13. A API do plicflix para o seu servidor

Todas as rotas usam Authorization: Bearer pk_…. A lista completa está em API e, para máquinas, em /openapi.json.

14. Unity, Godot, jogos sem servidor e outros motores

Está tudo em MOTORES, com arquivos prontos para baixar. Resumo:

15. Segurança

1. A chave pk_ fica só no servidor. Nunca no navegador nem no app.
2. Confira o token no servidor. O que vem do navegador pode ser falsificado; quem diz quem é o jogador é a troca do token.
3. Confira o jogo na resposta da troca.
4. O ir até vai pelo jogador_id, no servidor. Nunca pelo ponto vindo do navegador.
5. Reserve o login interno das contas do plicflix e recuse esse domínio no cadastro normal.
6. O frame-ancestors lista só as origens do plicflix, nunca *.
7. O cookie SameSite=None vai só na sessão criada pelo plicflix, e sempre Partitioned.
8. O que o plicflix nunca manda: e-mail, dados de pagamento ou a conta plicflix do jogador. Não peça.

16. Testar antes de publicar

O teste é no plicflix de verdade (https://plicflix.com), como testador do seu próprio jogo. Não precisa de assinatura nem de publicar.

1. No painel (developers), cadastre o jogo. Enquanto testa, o endereço pode ser a sua máquina: http://localhost:4100/ (e a rota de status, http://localhost:4100/saude).
2. Na aba Testadores, adicione o e-mail da sua conta do plicflix (crie uma em https://plicflix.com e confirme o e-mail com o código).
3. Rode o jogo na sua máquina com a chave: PLICFLIX_CHAVE=pk_… node server.mjs. O frame-ancestors precisa ter https://plicflix.com.
4. Abra https://plicflix.com com a conta testadora: o jogo aparece em "Em teste (só você vê)". Toque em Jogar. O app abre o seu localhost dentro dele (o Chrome e o Edge aceitam http://localhost dentro de uma página https).
5. Confira no painel, aba Integração: a "Entrada pelo SDK" e a "Tela de carregamento" ficam verdes quando acontecem de verdade.
6. Amigos: com duas contas testadoras em duas janelas (uma anônima), adicione uma à outra pelo código de amigo, entre no jogo com uma e use "Ir até" na outra.
7. Antes de enviar para revisão, ponha o jogo num endereço público com https e troque no painel: aba Integração → Endereço do jogo (o item "Endereço público" da lista trava o envio enquanto for localhost). Depois de trocar, espere a vigia ver o servidor no ar (até 2 minutos).

Sem o app (num teste automático, por exemplo), dá para fazer a parte do jogador pela API com a conta testadora — veja API.

17. Lista de conferência

Obrigatório

1. plicflix.js carregado antes do jogo.
2. Plicflix.entrar("/sua/rota") antes do seu login.
3. A rota no servidor que troca o token com a PLICFLIX_CHAVE e confere o jogo.
4. A conta ligada a jogador.id, sem senha utilizável, e o login interno reservado.
5. frame-ancestors com as origens do plicflix, e nenhum X-Frame-Options: DENY.
6. O cookie da sessão do plicflix com SameSite=None; Secure; Partitioned, apagado também ao sair da conta.
7. Plicflix.pronto() quando o jogador puder jogar.
8. Plicflix.aoSair salvando o progresso.
9. Uma status_url que responde 200.

Recomendado 10. Plicflix.progresso durante o carregamento, e Plicflix.erro quando não der para abrir. 11. Plicflix.onde({ texto, area, ponto }) a cada troca de lugar. 12. Plicflix.aoIrPara levando até o amigo pelo jogador_id, no servidor, só para lugares permitidos e com motivo claro quando recusar. 13. Um botão "Chamar amigos" no jogo com Plicflix.abrirAmigos().

Teste final 14. Abra pelo app, na web e no celular: - entra sem pedir login; - a tela de carregamento sai sozinha; - a bolha arrasta; - "Sair do jogo" fecha em menos de 5 s; - com duas contas amigas, "Ir até" leva uma até a outra.

18. Versões do SDK

As versões novas não quebram as antigas: um jogo com a 2.0 continua funcionando com o app atual, só sem os recursos novos.