# plicflix developers — a documentação inteira

Fonte: https://developers.plicflix.com/llms.txt



---

<!-- https://developers.plicflix.com/docs/COMECE.md -->

# Comece aqui: do zero ao jogo publicado

Este é o roteiro completo para pôr um jogo no plicflix. Foi escrito para ser
seguido **ao pé da letra**, por uma pessoa ou por uma IA. Cada passo diz o
que fazer, onde, e como saber que deu certo.

> **Para IAs:** a lista de todas as páginas em texto puro está em
> `https://developers.plicflix.com/llms.txt`, e tudo junto em
> `https://developers.plicflix.com/llms-full.txt`. Cada página também existe
> em Markdown: some `.md` ao endereço (ex.: `/docs/COMECE.md`). A API está
> descrita em `https://developers.plicflix.com/openapi.json`.

## O que é o plicflix (em 30 segundos)

- Um app de assinatura de jogos (web, Android, iOS). O jogador paga a
  assinatura e joga os jogos parceiros.
- **O plicflix nunca hospeda o seu jogo.** O app abre o **seu** endereço
  (iframe na web, WebView no celular) com a tela de carregamento do plicflix
  na frente e a bolha do plicflix (avisos, amigos, sair) por cima.
- O jogador **já chega logado**: o app manda um token de uso único; o **seu
  servidor** troca o token na API do plicflix e recebe só `id` (`pf_…`) e
  `nome` do jogador.
- **Fora do app**, o seu site ou app nativo pode ter o botão **"Entrar com
  Plicflix"** (OAuth 2.0 + PKCE): chega o **mesmo** jogador `pf_…`. Isso é
  opcional e pode vir depois do passo 11. Veja [OAUTH](OAUTH.md).
- **Você recebe** 60% do líquido de cada assinante, dividido entre os jogos
  que ele jogou, pelo tempo ativo (veja [REGRAS](REGRAS)).

## Os endereços

| o quê | endereço |
|---|---|
| este portal (cadastro, painel, documentação) | `https://developers.plicflix.com` |
| o app (onde jogadores e testadores jogam) | `https://plicflix.com` |
| a API (o seu servidor chama) | `https://api.plicflix.com` |
| o SDK do navegador (CDN) | `https://sdk.plicflix.com/plicflix.js` |
| a origem que vai no seu `frame-ancestors` | `https://plicflix.com` |
| suporte | `suporte@plicflix.com` |

Não existe um "ambiente de testes" separado: você testa no plicflix de verdade,
como **testador** do seu próprio jogo ainda não publicado (passo 8). Só você e
quem você indicar enxergam o jogo até a equipe publicar.

## Requisitos do jogo

1. **Ter uma versão web** (HTML5: JavaScript, WebAssembly, Unity WebGL, Godot
   Web, Flutter web…) num endereço seu. Jogos só nativos (sem versão web) ainda
   não entram.
2. **De preferência, ter um servidor** (qualquer linguagem). É ele quem troca
   o token com a chave secreta e guarda o progresso. Sem servidor dá para
   integrar ([MOTORES](MOTORES#jogo-sem-servidor)), com limitações.
3. **Poder mudar os cabeçalhos HTTP** da página do jogo (`Content-Security-Policy`
   e cookies). Hospedagens estáticas como Netlify, Vercel e Cloudflare Pages
   deixam, por arquivo de configuração.

## O roteiro

### 1. Criar a conta de desenvolvedor

- **Onde:** `https://developers.plicflix.com/cadastro`.
- **O quê:** o seu nome, o e-mail, uma senha (10 ou mais caracteres) e o
  estúdio (nome, CPF ou CNPJ — com ou sem pontuação —, país, site). Aceite os
  [termos](TERMOS).
- **Deu certo quando:** você cai no painel e chega um e-mail de boas-vindas
  com o link de confirmar o endereço e a fatura da taxa de entrada.

### 2. Pagar a taxa de entrada

- **Onde:** no painel, a fatura aparece logo no topo (`/faturas/{id}`).
- **Como:** enquanto o pagamento on-line não está ligado, responda ao e-mail
  da fatura (ou escreva para `suporte@plicflix.com`) com o número da fatura:
  mandamos o Pix ou o boleto. A equipe dá baixa e você recebe o e-mail
  "Pagamento confirmado".
- **Enquanto isso:** você já pode ler toda a documentação, baixar o SDK e os
  exemplos e montar a integração. Só cadastrar jogo e gerar a chave esperam o
  pagamento.

### 3. Gerar a chave de integração

- **Onde:** painel → **Gerar chave**.
- **O quê:** uma chave `pk_…`. **Aparece uma vez.** Guarde no seu servidor
  como variável de ambiente `PLICFLIX_CHAVE`. Nunca ponha no navegador, no app
  nem no git.
- **Perdeu?** Gere outra: a antiga para de funcionar na hora.

### 4. Cadastrar o jogo

- **Onde:** painel → **Novo jogo** (`/jogos/novo`).

| campo | exemplo | regra |
|---|---|---|
| nome | `Ilha das Luzes` | até 60 letras |
| identificador (slug) | `ilha-das-luzes` | minúsculas, números e `-`; não muda depois; volta como `jogo` na troca do token |
| endereço | `https://ilha.exemplo.com/` | https; **para testar, pode ser** `http://localhost:4100/` |
| rota de status | `https://ilha.exemplo.com/saude` | responde 200 rápido; a vigia consulta a cada minuto |

- **Deu certo quando:** o jogo aparece no painel com a situação **rascunho**
  (não publicado).
- **O endereço muda depois** (aba **Integração → Endereço do jogo**), enquanto
  o jogo estiver em rascunho ou recusado. O slug não muda nunca.

### 5. Integrar o navegador (o SDK)

Baixe [`plicflix.js`](/sdk/plicflix.js?baixar=1) para o seu site (sem mudar
nada) e carregue **antes** do jogo. Na ordem:

```js
// jogo.js — carregado com <script type="module" src="/jogo.js"> depois de <script src="/plicflix.js">
if (Plicflix.dentro()) {
  Plicflix.progresso(10, "Entrando…");                       // a tela do plicflix acompanha
  await Plicflix.entrar("/api/plicflix/entrar");             // passo 6: o SEU servidor troca o token
  Plicflix.aoSair(async () => { await salvarProgresso(); }); // o "Sair" da bolha espera (até 5 s)
  Plicflix.aoIrPara(async (destino) => levarAte(destino));   // opcional: "ir até o amigo"
}
// … carregue o jogo …
Plicflix.pronto();                                           // tira a tela de carregamento
Plicflix.onde({ texto: "Praia do Norte", area: "ilha/praia", ponto: { x: 10, y: 4 } }); // a cada troca de lugar
```

Referência completa: [SDK](SDK#11-referência-do-sdk). Tipos TypeScript:
[`plicflix.d.ts`](/sdk/plicflix.d.ts?baixar=1).

### 6. Integrar o servidor (a troca do token)

Uma rota sua recebe `{ token, contexto }` do `Plicflix.entrar` e faz:

```
POST https://api.plicflix.com/v1/ingresso/trocar
Authorization: Bearer <PLICFLIX_CHAVE>
Content-Type: application/json

{"token":"pft_…"}
```

Resposta 200:

```json
{"jogador":{"id":"pf_4olrydypdwdxj3adjnzjvgss","nome":"Ana"},"jogo":"ilha-das-luzes",
 "partida":"pt_…","assinante":true,"contexto":{"ref":"plicflix","idioma":"pt-BR","plataforma":"web"}}
```

Depois:
1. confira `jogo` == o seu slug;
2. ache ou crie a conta pelo `jogador.id` (fixo para essa pessoa no seu jogo)
   e atualize o `nome`;
3. abra a sessão com o cookie (escrito à mão, para não depender da versão da
   sua biblioteca de cookies)
   `Set-Cookie: sessao=…; Path=/; HttpOnly; Secure; SameSite=None; Partitioned`;
4. responda 200.

`401` = token inválido, vencido (5 min) ou já usado: peça para abrir de novo
pelo plicflix. Ajudantes prontos: [`plicflix.mjs`](/sdk/plicflix.mjs?baixar=1)
(Node) e [`plicflix.go`](/sdk/plicflix.go?baixar=1) (Go).

### 7. Deixar o plicflix abrir o jogo

Na página do jogo (e nas que ela abre):

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

E **nenhum** `X-Frame-Options`. Mais a rota de status respondendo 200.

**Atalho:** o [exemplo de referência](/sdk/exemplo-node.zip) (Node, sem
dependências) já faz os passos 5, 6 e 7. Rode com
`PLICFLIX_CHAVE=pk_… node server.mjs` e compare com o seu jogo. Também em
[Go](/sdk/exemplo-go.zip).

### 8. Testar como testador (sem publicar)

1. Crie uma conta de jogador em `https://plicflix.com` e confirme o e-mail
   (o código chega por e-mail).
2. No painel do jogo → aba **Testadores** → adicione o e-mail dessa conta.
3. Rode o jogo (pode ser em `http://localhost:4100`, se esse for o endereço
   cadastrado).
4. Abra `https://plicflix.com` com a conta testadora → fileira **"Em teste
   (só você vê)"** → **Jogar**. Testador não precisa de assinatura.

**Deu certo quando:**
- o jogo abre dentro do app **sem pedir login** e com o seu apelido;
- a tela de carregamento do plicflix some sozinha (o seu `pronto()`);
- a bolha do plicflix aparece por cima e dá para arrastar;
- **Sair do jogo** (no menu da bolha) fecha em menos de 5 s e o progresso
  ficou salvo;
- no painel, aba **Integração**, ficaram verdes "Entrada pelo SDK" e "Tela de
  carregamento".

Teste também no celular (o app web do plicflix funciona no navegador do
celular) e, se puder, no Safari.

### 9. Montar a vitrine

No painel do jogo:
- **aba Vitrine:** frase de chamada, descrições, gêneros, tags, classificação
  indicativa, plataformas e cor;
- **aba Imagens e vídeo:** banner, pôster, logo transparente, 3 a 12 capturas
  e o trailer (opcional).

Tudo é conferido no envio, com a qualidade mínima ([VITRINE](VITRINE)): o
painel diz exatamente o que está fora do padrão. A aba **Como vai ficar**
mostra a prévia no app.

### 10. Conferir e enviar para revisão

1. Ponha o jogo no **endereço público com https** e troque no painel (aba
   **Integração → Endereço do jogo**), se estava em `localhost`. Espere a vigia
   ver o servidor no ar (até 2 minutos): "Servidor no ar" fica verde.
2. Aba **Integração** → **Conferir agora**. O verificador visita o jogo como o
   app faria: HTTPS, a página responde, o iframe é permitido para
   `https://plicflix.com`, a página carrega o `plicflix.js`, a rota de status
   responde.
3. Com a lista de conferência sem nenhum item obrigatório faltando →
   **Enviar para revisão**.

**Deu certo quando:** a situação vira **em revisão** e chega o e-mail
"Recebemos o …". A equipe responde por e-mail, em geral em até 3 dias úteis:
**publicado** (o jogo entra no catálogo de todos) ou **recusado com o
motivo** (corrija e envie de novo).

### 11. Depois de publicado

- Mantenha a **rota de status** respondendo: fora do ar, o app não deixa
  abrir.
- Responda aos **casos de reclamação** em até 48 horas úteis ([REGRAS](REGRAS#reclamações)):
  chega um e-mail quando um caso abre.
- Acompanhe o repasse em `GET /v1/parceiro/repasses` ([API](API)).
- Atualize a vitrine quando quiser (novas capturas, textos): não precisa de
  nova revisão para isso.

## A lista final (copie e marque)

**Obrigatório**
- [ ] `plicflix.js` carregado antes do jogo (cópia sem mudança ou a CDN).
- [ ] `Plicflix.entrar("/sua/rota")` quando `Plicflix.dentro()`.
- [ ] A rota do servidor troca o token com `PLICFLIX_CHAVE` (só no servidor) e confere `jogo`.
- [ ] A conta ligada a `jogador.id` (único), sem senha utilizável, nome atualizado a cada entrada.
- [ ] `Content-Security-Policy: frame-ancestors 'self' https://plicflix.com` e nenhum `X-Frame-Options`.
- [ ] Cookie da sessão com `SameSite=None; Secure; Partitioned` (e apagado ao sair da conta).
- [ ] `Plicflix.pronto()` quando o jogador puder jogar.
- [ ] `Plicflix.aoSair` salvando o progresso (até 5 s).
- [ ] Rota de status respondendo 200.
- [ ] Endereço público com https.
- [ ] Vitrine completa com a qualidade mínima.

**Recomendado**
- [ ] `Plicflix.progresso` durante o carregamento e `Plicflix.erro` se não der para abrir.
- [ ] `Plicflix.onde({ texto, area, ponto })` a cada troca de lugar.
- [ ] `Plicflix.aoIrPara` levando até o amigo pelo `jogador_id`, decidido no servidor.
- [ ] Um botão "Chamar amigos" com `Plicflix.abrirAmigos()`.

## Erros comuns

| sintoma | causa | conserto |
|---|---|---|
| tela branca dentro do app; o console fala em `frame-ancestors` | o `frame-ancestors` não tem `https://plicflix.com`, ou há `X-Frame-Options` | ajuste os cabeçalhos (passo 7) |
| `Plicflix.entrar` dá 401 | token vencido (mais de 5 min), já trocado, de outro estúdio ou chave errada | abra de novo pelo app; confira `PLICFLIX_CHAVE` e o `PLICFLIX_API` |
| entra, mas ao recarregar pede login | o cookie sem `SameSite=None; Secure; Partitioned` | passo 6.3 |
| a tela de carregamento fica 12 s e some sozinha | o jogo não chama `Plicflix.pronto()` | chame quando o jogador puder jogar |
| "Sair do jogo" demora 5 s | o `aoSair` não terminou | salve mais rápido ou salve sempre, e no `aoSair` só feche |
| `await` dá erro de sintaxe | o script não é módulo | `<script type="module">` ou um arquivo `.js` com `type="module"` |
| o jogo não aparece no app | a conta não é testadora, ou o e-mail não foi confirmado | passo 8 |
| "Endereço público" vermelho | o endereço ainda é `localhost` | publique o jogo num https e troque no painel |

## Ajuda

`suporte@plicflix.com`. Diga o identificador do jogo e o que você já tentou.


---

<!-- https://developers.plicflix.com/docs/SDK.md -->

# 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.4.0**.

> **Login fora do app?** O botão "Entrar com Plicflix" no seu site ou app
> nativo (OAuth 2.0 + PKCE, o mesmo jogador `pf_…`) está em [OAUTH](OAUTH.md).

> **É uma IA fazendo a integração?** Comece por [COMECE](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](#1-como-funciona)
2. [Antes de começar: o cadastro](#2-antes-de-começar-o-cadastro)
3. [Começo rápido](#3-começo-rápido)
4. [Entrada: o jogador já chega logado](#4-entrada-o-jogador-já-chega-logado)
5. [Deixar o plicflix abrir o seu jogo](#5-deixar-o-plicflix-abrir-o-seu-jogo)
6. [A tela de carregamento](#6-a-tela-de-carregamento)
7. [A bolha do plicflix](#7-a-bolha-do-plicflix)
8. [Sair salvando](#8-sair-salvando)
9. [Onde o jogador está](#9-onde-o-jogador-está)
10. [Amigos: "Ir até" e "Chamar para cá"](#10-amigos-ir-até-e-chamar-para-cá)
11. [Referência do SDK](#11-referência-do-sdk)
12. [O protocolo de mensagens (sem o SDK em JavaScript)](#12-o-protocolo-de-mensagens-sem-o-sdk-em-javascript)
13. [A API do plicflix para o seu servidor](#13-a-api-do-plicflix-para-o-seu-servidor)
14. [Unity, Godot, jogos sem servidor e outros motores](#14-unity-godot-jogos-sem-servidor-e-outros-motores)
15. [Segurança](#15-segurança)
16. [Testar antes de publicar](#16-testar-antes-de-publicar)
17. [Lista de conferência](#17-lista-de-conferência)
18. [Versões do SDK](#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:

| o plicflix faz | o seu jogo faz |
|---|---|
| conta, assinatura e catálogo | o jogo, no **seu** servidor (o plicflix nunca hospeda o jogo de ninguém) |
| abrir o jogo e a tela de carregamento | trocar o token e criar a sessão |
| a bolha por cima do jogo: avisos, amigos, sair, reclamar | salvar o progresso quando o jogador sai |
| medir o tempo de jogo e dividir os 60% ([REGRAS](REGRAS#repasse)) | contar onde o jogador está (opcional, mas recomendado) |
| vigiar se o seu servidor está no ar | levar o jogador até o amigo, se o seu jogo permitir |

**Só dois dados do jogador chegam ao seu jogo:**

| campo | exemplo | o que é |
|---|---|---|
| `id` | `pf_4olrydypdwdxj3adjnzjvgss` | O código do jogador **no seu jogo**. É fixo para essa pessoa e diferente em cada jogo, então dois estúdios não conseguem cruzar quem é quem. Use como chave da conta. |
| `nome` | `Paulo` | O apelido, com até 24 letras. Serve para mostrar na tela. |

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](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](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:

| campo | exemplo | para quê |
|---|---|---|
| identificador (`slug`) | `meu-jogo` | O nome do jogo na API. Volta como `jogo` na troca do token. Letras minúsculas, números e `-`. |
| endereço (`url`) | `https://meu-jogo.com/` | A página que o app abre. HTTPS (para testar antes de publicar, vale `http://localhost:PORTA/`). |
| rota de status (`status_url`) | `https://meu-jogo.com/saude` | Uma rota barata que responda 200. A vigia do plicflix consulta de minuto em minuto. |

Depois de cadastrado, a vitrine é editada no painel (ou por
`PUT /v1/parceiro/jogos/{slug}`, veja [API](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'`):

```html
<!-- 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>
```

```js
// 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):**

```js
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`](/sdk/exemplo-node.zip) ou [`exemplo-go.zip`](/sdk/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](#5-deixar-o-plicflix-abrir-o-seu-jogo).

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**:

```json
{ "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`](/sdk/plicflix.mjs?baixar=1) →
  `await trocarIngresso(token)`;
- **Go:** [`plicflix.go`](/sdk/plicflix.go?baixar=1) →
  `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`):

| ambiente | origem |
|---|---|
| produção (o app que os jogadores e os testadores usam) | `https://plicflix.com` |

É 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.

| o seu jogo faz | o app faz |
|---|---|
| carrega o SDK | entende que o jogo vai avisar (texto "Entrando…") |
| `Plicflix.progresso(40, "Carregando o mapa…")` | a barra em 40% e o seu texto |
| `Plicflix.pronto()` | a tela some, e o tempo de jogo começa a contar |
| `Plicflix.erro("Servidor em manutenção")` | a sua mensagem, com os botões "Tentar de novo" e "Voltar" |
| não usa o SDK | a tela some 2,5 s depois de a página carregar |
| usa o SDK, mas não chama `pronto()` | a tela some 12 s depois de a página carregar |
| passou de 25 s | "Está demorando mais que o normal": continuar esperando, tentar de novo (com outro token) ou voltar |

**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.
```

```js
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**:

```js
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:**

| campo | quem vê | para quê |
|---|---|---|
| `texto` | o jogador (na bolha) e os amigos (se a privacidade dele deixar) | "Ana — Jogando Ilha das Luzes · Taverna do Porto" |
| `area` | ninguém, por enquanto | agrupar (ex.: quantos estão na taverna) |
| `ponto` | **ninguém além do seu jogo** | volta para o seu jogo no "ir até" |

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](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

```js
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

| função | quando usar |
|---|---|
| `Plicflix.dentro()` | `true` quando o jogo foi aberto pelo plicflix. |
| `Plicflix.token()` | O token de uso único, ou `null`. |
| `Plicflix.contexto()` | `{ ref: "plicflix", idioma, plataforma }` (`web`, `android` ou `ios`). |
| `Plicflix.entrar(url, { credentials?, headers? })` | Faz `POST url` com `{ token, contexto }` (`credentials: "include"` por padrão). Devolve o JSON do seu servidor ou lança um erro com `.status`. Depois disso o token é esquecido. |
| `Plicflix.jogador()` | **Jogo sem servidor:** troca o token direto da página e devolve `{ jogador: { id, nome }, jogo, contexto, pelo_navegador: true }`. Veja a seção 14. |
| `Plicflix.progresso(pct, texto)` | Avança a barra (0 a 100) e troca o texto da tela de carregamento. |
| `Plicflix.pronto()` | Tira a tela de carregamento. |
| `Plicflix.erro(texto)` | Mostra a sua mensagem e oferece "tentar de novo". |
| `Plicflix.aoSair(fn)` | Roda antes de fechar: salve ali (espera de até 5 s). |
| `Plicflix.sair()` | O jogo fecha a si mesmo e volta ao catálogo. |
| `Plicflix.onde(texto \| { texto, area?, ponto? })` | Onde o jogador está. |
| `Plicflix.aoIrPara(fn)` | Leve o jogador até `destino` e devolva `true`, `false` ou `{ ok, motivo }`. |
| `Plicflix.abrirAmigos()` | Abre a lista de amigos da bolha. |
| `Plicflix.entrarComPlicflix({ cliente, volta, prompt? })` | **Fora do app:** vai para o "Entrar com Plicflix" (OAuth + PKCE). Veja [OAUTH](OAUTH.md). |
| `Plicflix.voltouDoPlicflix({ servidor? })` | Na página de volta: confere o `state` e troca o código (no seu servidor ou direto). `null` sem `?code`. |
| `Plicflix.botaoEntrar(onde, { cliente, volta } \| { href })` | O botão oficial "Entrar com Plicflix". |
| `Plicflix.versao` | `"2.4.0"` |

Como distribuir o SDK:
- **Copie** [`plicflix.js`](/sdk/plicflix.js?baixar=1) para o seu site **sem
  mudar nada**. Assim ele passa pela sua CSP `script-src 'self'`.
- **Tipos TypeScript:** [`plicflix.d.ts`](/sdk/plicflix.d.ts?baixar=1).
- **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

| sentido | web (iframe) | celular (WebView) |
|---|---|---|
| jogo → app | `window.parent.postMessage({ plicflix: msg }, "*")` | `window.PlicflixApp.postMessage(JSON.stringify(msg))` |
| app → jogo | `message` com `event.data.plicflixApp = msg`, vindo de `window.parent` | o app chama `window.__plicflixApp(json)` |

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

### As mensagens

| mensagem | sentido | campos |
|---|---|---|
| `ola` | jogo → app | `versao`, `recursos[]`. Avisa que o jogo usa o SDK. |
| `progresso` | jogo → app | `pct` (0 a 100), `texto` |
| `pronto` | jogo → app | — |
| `erro` | jogo → app | `texto` |
| `onde` | jogo → app | `texto`, `area?`, `ponto?` |
| `sair` | jogo → app | — |
| `abrirAmigos` | jogo → app | — |
| `saindo` | app → jogo | — (responda com `saiu`) |
| `saiu` | jogo → app | — |
| `irPara` | app → jogo | `destino` (veja a seção 10), `pedido` (número) |
| `foiPara` | jogo → app | `ok`, `motivo?`, `pedido` (o mesmo do `irPara`) |

---

## 13. A API do plicflix para o seu servidor

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

| rota | o quê |
|---|---|
| `POST /v1/ingresso/trocar` `{token}` | A troca do token (seção 4). |
| `GET /v1/parceiro/jogos` | Os seus jogos. |
| `PUT /v1/parceiro/jogos/{slug}` | Edita a vitrine (veja [VITRINE](VITRINE)). Não muda `url` nem `tipo`. |
| `GET /v1/parceiro/casos` | Casos de reclamação, com motivos e prazo (veja [REGRAS](REGRAS#reclamações)). |
| `POST /v1/parceiro/casos/{id}/prova` `{prova}` | A prova da correção, dentro de 48 horas úteis. |
| `GET /v1/parceiro/repasses` | O extrato por mês (veja [REGRAS](REGRAS#repasse)). |

---

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

Está tudo em [MOTORES](MOTORES), com arquivos prontos para baixar. Resumo:

| o seu jogo | o que fazer |
|---|---|
| web com servidor (Node, Go, PHP, Python…) | este guia, como está |
| **Unity WebGL** | [`Plicflix.jslib`](/sdk/unity/Plicflix.jslib?baixar=1) + [`Plicflix.cs`](/sdk/unity/Plicflix.cs?baixar=1) |
| **Godot 4 (Web)** | [`plicflix.gd`](/sdk/godot/plicflix.gd?baixar=1) como Autoload |
| **sem servidor** (só arquivos estáticos) | `Plicflix.jogador()` no lugar do `entrar` — não protege nada de valor |
| Flutter web, Construct, Phaser, PixiJS, Three.js… | chame o `window.Plicflix` como em JavaScript (Flutter: `dart:js_interop`) |
| **só app nativo** (Android/iOS/PC sem versão web) | ainda não dá: o plicflix abre jogos pela web |

## 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](API#testar-pela-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

| versão | o que mudou |
|---|---|
| **2.4.0** | "Entrar com Plicflix" fora do app: `entrarComPlicflix`, `voltouDoPlicflix`, `botaoEntrar` ([OAUTH](OAUTH.md)). |
| 2.3.0 | `Plicflix.jogador()` (jogos sem servidor) e `pf_api` no endereço. |
| 2.2.0 | `onde` aceita objeto (`texto`, `area`, `ponto`) e não repete o mesmo lugar seguido. Novidades: `aoIrPara` (ir até o amigo, com resposta `foiPara`), `abrirAmigos`, e `recursos[]` no `ola`. |
| 2.1.0 | `aoSair` (sair salvando) e `onde` (só texto). |
| 2.0.0 | O token opaco de uso único trocado pelo servidor do jogo, mais `progresso`, `pronto` e `erro`. |
| 1.x | (descontinuado) ingresso JWT assinado, conferido pela chave pública. |

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.


---

<!-- https://developers.plicflix.com/docs/OAUTH.md -->

# Entrar com Plicflix (fora do app)

O botão **"Entrar com Plicflix"** no **seu** site ou app. O jogador entra com a
conta do plicflix e o seu jogo recebe **o mesmo jogador** da entrada pelo app:
o mesmo `id` (`pf_…`, fixo por pessoa e por jogo) e o mesmo apelido. Assim, uma
conta do seu jogo serve às duas portas:

| porta | quando | como o jogo recebe o jogador |
|---|---|---|
| **pelo app** ([SDK](SDK)) | o jogador toca em Jogar no plicflix | token `pft_…` no endereço → `POST /v1/ingresso/trocar` |
| **fora do app** (esta página) | o jogador abriu o seu site direto, ou o seu app nativo | OAuth 2.0 + PKCE → `POST /v1/oauth/token` |

É OAuth 2.0 padrão (RFC 6749), com **PKCE S256 obrigatório** (RFC 7636). Qualquer
biblioteca de OAuth serve. O plicflix **não** emite `id_token`: o jogador vem
direto na resposta do token.

> **Para IAs:** siga as seções 1 a 5 na ordem. A seção 4 é o caminho
> recomendado (com servidor). O exemplo inteiro, em Node, está na seção 4.3.
> Os ajudantes prontos ficam em [`plicflix.mjs`](/sdk/plicflix.mjs?baixar=1) e
> [`plicflix.go`](/sdk/plicflix.go?baixar=1) (servidor) e
> [`plicflix.js`](/sdk/plicflix.js?baixar=1) 2.4+ (navegador).

## 1. Os endereços

| o quê | endereço |
|---|---|
| autorizar (o navegador vai até lá) | `https://plicflix.com/oauth/authorize` |
| trocar o código | `POST https://api.plicflix.com/v1/oauth/token` |
| quem é (com o access token) | `GET https://api.plicflix.com/v1/oauth/userinfo` |
| revogar o access token | `POST https://api.plicflix.com/v1/oauth/revogar` |
| descoberta (RFC 8414) | `https://plicflix.com/.well-known/oauth-authorization-server` |
| `client_id` | o **slug** do seu jogo |
| `client_secret` (opcional) | a **chave `pk_…`** do seu estúdio |
| escopo | `perfil` (`openid` e `profile` são aceitos como sinônimos) |

## 2. Cadastrar os endereços de volta

No portal: **developers.plicflix.com → o seu jogo → Integração → Entrar com
Plicflix**, um `redirect_uri` por linha (até 10). Ou pela API, com a chave:

```bash
curl -X PUT https://api.plicflix.com/v1/parceiro/jogos/SEU-SLUG/oauth \
  -H "Authorization: Bearer pk_…" -H "Content-Type: application/json" \
  -d '{"redirect_uris":["https://seujogo.com/api/plicflix/volta","http://localhost:5173/api/plicflix/volta"]}'
# → {"client_id":"SEU-SLUG","redirect_uris":[…],"authorization_endpoint":…,"token_endpoint":…}
```

As regras:
- `https://…`. `http://` só vale em `localhost`, `127.0.0.1` e `::1` (para testar).
- App nativo: um esquema próprio com ponto no nome (`com.estudio.jogo:/oauth`,
  RFC 8252).
- Sem `#`. A comparação é **exata**, caractere por caractere, inclusive a query.
- Vale em qualquer situação do jogo: rascunho, revisão ou publicado. O login é
  do **seu site**, não do catálogo. O que se exige é o estúdio **ativo** (taxa
  de entrada paga, não suspenso). Sem isso, a página mostra o erro e não volta.

## 3. O fluxo

```
seu jogo                         navegador                       plicflix
   │ 1. gera verifier + state       │                                │
   │──── 302 /oauth/authorize ─────▶│──────────────────────────────▶ │ 2. entra (se precisar)
   │                                │                                │    e autoriza (1ª vez)
   │◀──── redirect_uri?code&state ──│◀────────────────────────────── │
   │ 3. confere o state                                              │
   │──── POST /v1/oauth/token (code + verifier [+ pk_]) ───────────▶ │
   │◀─── { jogador: { id: "pf_…", nome }, jogo, assinante, access_token } │
   │ 4. acha/cria a conta por jogador.id e abre a SUA sessão         │
```

**1. Mandar o navegador** para:

```
https://plicflix.com/oauth/authorize?response_type=code
  &client_id=SEU-SLUG
  &redirect_uri=https%3A%2F%2Fseujogo.com%2Fapi%2Fplicflix%2Fvolta
  &state=ALEATORIO            ← guarde (cookie curto); confira na volta
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256
  &scope=perfil
  [&prompt=consent]           ← pergunta de novo mesmo se já autorizou
```

O `verifier` tem de 43 a 128 caracteres de `[A-Za-z0-9-._~]` (por exemplo, 48
bytes aleatórios em base64url).

**2. O plicflix cuida do resto:**
- quem já está logado no plicflix nesse navegador não digita nada;
- quem não está entra, ou cria a conta e confirma o e-mail, ali mesmo;
- da segunda vez em diante a autorização é automática: o jogador nem vê a tela.

A tela mostra o que o jogo recebe (o apelido, um id só deste jogo e se é
assinante) e o que **nunca** recebe (o e-mail, a senha, os amigos).

**3. A volta.** O navegador chega em `redirect_uri?code=pfc_…&state=…`. Se o
jogador cancelou, chega com `error=access_denied&state=…`. O código vale **5
minutos e uma troca**.

Um pedido malformado volta com `error=invalid_request`, `invalid_scope` ou
`unsupported_response_type`. Se o `client_id` ou o `redirect_uri` não
conferem, o plicflix **não** volta: mostra o erro na própria página.

**4. A troca**, de preferência no seu servidor:

```bash
curl -X POST https://api.plicflix.com/v1/oauth/token \
  -u "SEU-SLUG:pk_…" \
  -d grant_type=authorization_code -d code=pfc_… \
  -d redirect_uri=https://seujogo.com/api/plicflix/volta -d code_verifier=…
```

```json
{
  "jogador": { "id": "pf_3k2j…", "nome": "Ana" },
  "jogo": "seu-slug",
  "assinante": true,
  "sub": "pf_3k2j…",
  "name": "Ana",
  "access_token": "pfa_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "perfil"
}
```

- O corpo pode ser `application/x-www-form-urlencoded` (o padrão) ou JSON.
- A chave vai como Basic (`client_id:pk_…`), como `client_secret` no corpo ou
  como `Authorization: Bearer pk_…`.
- **Sem a chave**, o pedido é de um cliente público (o jogo sem servidor, o app
  nativo): o PKCE é a prova.
- `jogador.id` é **igual** ao da entrada pelo app (`/v1/ingresso/trocar`):
  ligue a conta por ele.

**5. Depois:** o `access_token` vale **1 hora** e só serve para
`GET /v1/oauth/userinfo`, que devolve as mesmas chaves (sem o token). Não há
refresh token: o seu jogo abre a **própria** sessão. Para saber de novo quem
é, repita o fluxo; da segunda vez em diante ele é automático e invisível.

## 4. Com servidor (recomendado)

### 4.1 As duas rotas

- `GET /api/plicflix/oauth`:
  1. gere `verifier` e `state` (`novoPKCE()`);
  2. guarde os dois num cookie `HttpOnly; Secure; SameSite=Lax` de 10 minutos;
  3. responda `302` para `urlDeEntrada(...)`.
- `GET /api/plicflix/volta`:
  1. confira `state` contra o cookie e apague o cookie;
  2. se veio `error`, mande o jogador de volta à sua tela de login;
  3. chame `trocarCodigo(code, …)` com a chave `pk_`;
  4. ache ou crie a conta por `jogador.id`, abra a sessão e responda `302` para
     o jogo.

A conta segue as mesmas regras da entrada pelo app ([SDK](SDK#a-conta)): coluna
única `plicflix_id`, login interno reservado (`pf_…@plicflix.invalid`) e apelido
atualizado a cada entrada.

### 4.2 O botão

Um link para a sua rota, com a cara oficial:

```html
<script src="/plicflix.js"></script>
<div id="entrar-plicflix"></div>
<script>Plicflix.botaoEntrar("#entrar-plicflix", { href: "/api/plicflix/oauth", largura: "100%" });</script>
```

Ou faça o seu: o texto é **"Entrar com Plicflix"** ("Sign in with Plicflix"), o
fundo vai de `#DC0DF7` a `#A104F8` e o texto é branco.

### 4.3 Exemplo completo (Node 18+, sem dependências)

```js
import { createServer } from "node:http";
import { novoPKCE, urlDeEntrada, trocarCodigo } from "./plicflix.mjs"; // PLICFLIX_CHAVE no ambiente

const CLIENTE = "seu-slug";
const VOLTA = "https://seujogo.com/api/plicflix/volta";
const cookies = (req) => Object.fromEntries((req.headers.cookie || "").split(/; */).filter(Boolean).map((c) => c.split("=").map(decodeURIComponent)));

createServer(async (req, res) => {
  const url = new URL(req.url, "https://seujogo.com");
  if (url.pathname === "/api/plicflix/oauth") {
    const { verificador, desafio, estado } = novoPKCE();
    res.writeHead(302, {
      "Set-Cookie": `pf_oauth=${estado}.${verificador}; Path=/api/plicflix; HttpOnly; Secure; SameSite=Lax; Max-Age=600`,
      Location: urlDeEntrada({ cliente: CLIENTE, volta: VOLTA, desafio, estado }),
    });
    return res.end();
  }
  if (url.pathname === "/api/plicflix/volta") {
    const [estado, verificador] = (cookies(req).pf_oauth || ".").split(".");
    const apagar = "pf_oauth=; Path=/api/plicflix; Max-Age=0";
    if (!estado || url.searchParams.get("state") !== estado || !url.searchParams.get("code")) {
      res.writeHead(302, { "Set-Cookie": apagar, Location: "/sign-in?erro=plicflix" });
      return res.end();
    }
    const r = await trocarCodigo(url.searchParams.get("code"), { cliente: CLIENTE, volta: VOLTA, verificador });
    const conta = await acharOuCriarConta(r.jogador.id, r.jogador.nome); // a SUA conta
    res.writeHead(302, { "Set-Cookie": [apagar, await abrirSessao(conta)], Location: "/play" });
    return res.end();
  }
}).listen(8080);
```

Em Go é o mesmo, com `plicflix.NovoPKCE()`, `plicflix.URLDeEntrada(cliente,
volta, pk)` e `cliente.TrocarCodigo(ctx, cliente, code, volta, verificador)`.
Os dois ajudantes estão em [`plicflix.go`](/sdk/plicflix.go?baixar=1).

## 5. Sem servidor (jogo só de navegador)

O SDK faz tudo:

```html
<script src="/plicflix.js"></script>
<div id="entrar"></div>
<script type="module">
  const CLIENTE = "seu-slug", VOLTA = location.origin + "/";
  const r = await Plicflix.voltouDoPlicflix();        // na volta: troca direto na API (cliente público)
  if (r) iniciar(r.jogador);                          // { id: "pf_…", nome }
  else Plicflix.botaoEntrar("#entrar", { cliente: CLIENTE, volta: VOLTA });
</script>
```

- `voltouDoPlicflix()` confere o `state`, troca o código e limpa a URL.
- Com `{ servidor: "/sua/rota" }`, ele manda `{ code, code_verifier,
  redirect_uri }` ao seu servidor em vez de trocar direto. É o meio-termo para
  quem já tem uma página e quer trocar no servidor.
- Como tudo o que roda no navegador, o resultado de um cliente público serve
  para mostrar o nome e guardar o progresso local. **Nunca** use para proteger
  moedas, ranking ou compras: para isso, troque no servidor (seção 4).

## 6. Segurança (confira cada uma)

- [ ] O `state` é aleatório, fica num cookie `HttpOnly` e é conferido na volta.
- [ ] O `verifier` nunca sai do seu lado: só o `code_challenge` vai na URL.
- [ ] A chave `pk_…` só existe no servidor (nunca no navegador nem no app).
- [ ] A conta é achada por `jogador.id`, nunca pelo apelido (o apelido muda).
- [ ] O login interno `…@plicflix.invalid` é recusado no seu cadastro normal.
- [ ] Os `redirect_uri` de `localhost` saem da lista antes de publicar, se você
      não quiser que funcionem em produção.

## 7. Erros

O token responde no formato do OAuth: `{"error": "...", "error_description": "..."}`.

| status | `error` | quando |
|---|---|---|
| `400` | `invalid_grant` | o código é inválido, venceu (5 min), já foi usado ou é de outro jogo; ou o `redirect_uri` é diferente; ou o `code_verifier` não confere. Um código que falha **morre**: recomece o fluxo. |
| `400` | `invalid_request` | falta `code` ou `code_verifier`, ou o corpo é inválido |
| `400` | `unsupported_grant_type` | só `authorization_code` |
| `401` | `invalid_client` | o `client_id` não existe ou a chave não é do estúdio dono do jogo |
| `401` | `invalid_token` | userinfo: o `pfa_` é inválido ou venceu |
| `429` | — | limite por IP; espere um minuto |

Na volta para o seu `redirect_uri`, os erros possíveis são `access_denied` (o
jogador cancelou), `invalid_request` (faltou o PKCE S256), `invalid_scope` e
`unsupported_response_type`.

## 8. Testar

1. Cadastre `http://localhost:PORTA/api/plicflix/volta` (seção 2).
2. Use uma conta **testadora** do jogo (com o e-mail confirmado) se ele ainda
   não está publicado.
3. Abra `http://localhost:PORTA/api/plicflix/oauth` e entre: você volta logado
   no seu jogo. O `jogador.id` é o mesmo de quando a mesma conta abre o jogo
   pelo app.
4. Abra de novo: desta vez a volta é direta, sem a tela de autorizar. Para ver
   a tela outra vez, use `prompt=consent`.


---

<!-- https://developers.plicflix.com/docs/API.md -->

# A API do plicflix

- **Endereço:** `https://api.plicflix.com`
- **Formato:** JSON (`Content-Type: application/json`), UTF-8. Erros sempre no
  formato `{"erro": "mensagem"}` e, quando há um motivo para máquinas,
  `{"erro": "…", "codigo": "…"}`.
- **Corpo:** no máximo 64 KiB; campos desconhecidos são recusados (`400`).
- **Dinheiro:** em centavos. **Mês:** `AAAA-MM`, fuso de Brasília.
- **Limites:** cadastro, login e troca pelo navegador têm limite por IP (`429`
  ao passar).
- **Para máquinas:** [`/openapi.json`](/openapi.json) (OpenAPI 3.1).

## Rotas do estúdio (o SEU servidor)

Autenticação: `Authorization: Bearer pk_…` (a chave do painel). **Só no
servidor.**

### `POST /v1/ingresso/trocar` — a troca do token

```http
POST /v1/ingresso/trocar
Authorization: Bearer pk_…
Content-Type: application/json

{"token":"pft_…"}
```

| status | corpo |
|---|---|
| `200` | `{"jogador":{"id":"pf_…","nome":"Ana"},"jogo":"seu-slug","partida":"pt_…","assinante":true,"contexto":{"ref":"plicflix","idioma":"pt-BR","plataforma":"web"}}` |
| `401` | token inválido, vencido (5 min), já trocado, de jogo de outro estúdio, ou chave inválida/estúdio inativo. Sempre a mesma mensagem, de propósito. |

- `jogador.id`: `pf_` + 24 caracteres; **fixo** para essa pessoa no seu jogo e
  diferente em cada jogo.
- `jogador.nome`: o apelido (até 24 letras); pode mudar.
- `assinante`: `false` para testadores sem assinatura.

### `GET /v1/parceiro/jogos`

Os seus jogos: `{"parceiro":"Seu Estúdio","jogos":[{"slug","nome","url","tipo","ativo","situacao","motivo_recusa","status","status_url"}]}`.
`situacao`: `rascunho`, `em_revisao`, `recusado` ou `publicado`. `status`: o
que a vigia viu (`online`, `instavel`, `offline` ou vazio).

### `PUT /v1/parceiro/jogos/{slug}`

Edita a vitrine. **Parcial:** só os campos enviados mudam; os omitidos ficam
como estão. As imagens e o vídeo só mudam pelo painel (onde a qualidade é
conferida). Campos:
`nome, subtitulo, descricao, descricao_longa, estudio, generos[], tags[],
classificacao, plataformas[], multijogador, cor, status_url`. Regras em
[VITRINE](VITRINE). Não muda `url`, `slug` nem a situação.

### `GET /v1/parceiro/casos`

Os casos de reclamação: `{"casos":[{"id","jogo","mes","situacao","aberto_em","prazo","prova","prova_em","decidido_em","motivos":[…]}]}`.
`situacao`: `aberto`, `em_analise`, `corrigido` ou `perdido`.

### `POST /v1/parceiro/casos/{id}/prova`

`{"prova":"o que mudou e como conferir"}` → `200 {"situacao":"em_analise"}`. Fora do prazo: `409`.

### `GET /v1/parceiro/repasses`

O extrato: `{"repasses":[{"mes":"2026-11","jogo":"seu-slug","jogadores":120,"segundos":431000,"pago_centavos":53210,"retido_centavos":0}]}`.

## Rota do navegador (jogos sem servidor)

### `POST /v1/ingresso/navegador`

`{"token":"pft_…"}`, chamada **pela página do jogo** (o `Plicflix.jogador()`
faz isso). Sem chave; o cabeçalho `Origin` precisa ser a origem do endereço
cadastrado do jogo (senão `403`). Resposta igual à da troca, mais
`"pelo_navegador": true`. Veja [MOTORES](MOTORES#jogo-sem-servidor).

## Entrar com Plicflix (OAuth 2.0 + PKCE)

O login **fora do app** (o seu site, o seu app nativo). O guia completo, com
exemplos, está em [OAUTH](OAUTH.md).

| rota | o quê |
|---|---|
| `GET https://plicflix.com/oauth/authorize` | a página de autorizar: `response_type=code`, `client_id` (o slug), `redirect_uri` (cadastrado), `state`, `code_challenge` (S256, **obrigatório**), `scope=perfil`, `prompt=consent` (opcional) |
| `POST /v1/oauth/token` | `grant_type=authorization_code`, `code`, `redirect_uri`, `code_verifier`, `client_id`. A chave `pk_` é opcional (Basic, `client_secret` ou Bearer). Devolve `{jogador:{id,nome}, jogo, assinante, sub, name, access_token, token_type, expires_in, scope}`. |
| `GET /v1/oauth/userinfo` | `Authorization: Bearer pfa_…` → as mesmas chaves, sem o token |
| `POST /v1/oauth/revogar` | `token=pfa_…` → `200` (sempre) |
| `GET /v1/parceiro/jogos/{slug}/oauth` / `PUT` | os `redirect_uris` do jogo (`{"redirect_uris":[…]}`, até 10), com a chave `pk_` |
| `GET https://plicflix.com/.well-known/oauth-authorization-server` | a descoberta (RFC 8414); também em `/v1/oauth/descoberta` |

## Pública

| rota | o quê |
|---|---|
| `GET /saude` | `{"ok":true}` se a API está de pé. |
| `GET /v1/jogos/{slug}/status` | `{"status":"online"\|"instavel"\|"offline"\|"desconhecido","ms","em"}` (o que a vigia viu). |

## Testar pela API

Para um teste automático do seu jogo **sem o app**, faça a parte do jogador
pela API com uma conta **testadora** do seu jogo (passo 8 do [COMECE](COMECE)).
Autenticação do jogador: `Authorization: Bearer <token da conta>`.

```bash
API=https://api.plicflix.com
# 1. entrar (a conta já criada e com o e-mail confirmado; testadora do jogo)
TOK=$(curl -s -X POST $API/v1/entrar -d '{"email":"voce@estudio.com","senha":"…"}' | jq -r .token)
# 2. "tocar em Jogar": devolve a URL que o app abriria
curl -s -X POST $API/v1/jogos/SEU-SLUG/jogar -H "Authorization: Bearer $TOK" -d '{"plataforma":"web"}'
# → {"partida":"pt_…","url":"https://seu-jogo/?ref=plicflix#plicflix=pft_…&pf_idioma=pt-BR&pf_plataforma=web&pf_api=…", …}
# 3. abra essa URL num navegador automatizado (Playwright, Puppeteer) DENTRO de um iframe
#    numa página https de outro site, ou mande o token direto para a sua rota:
curl -s -X POST https://seu-jogo/api/plicflix/entrar -d '{"token":"pft_…"}'
```

O que o app faz durante a partida (para reproduzir num teste):

| rota | corpo | quando |
|---|---|---|
| `POST /v1/partidas/{partida}/carregou` | `{"ms":1800,"falha":""}` | quando o jogo chama `pronto()` (`falha`: `""`, `demorou`, `erro`, `desistiu`) |
| `POST /v1/partidas/{partida}/onde` | `{"texto":"…","area":"…","ponto":{…}}` | quando o jogo chama `onde()` |
| `POST /v1/partidas/{partida}/pulso` | `{"ativo_ms":30000}` | a cada 30 s de jogo |
| `POST /v1/partidas/{partida}/fim` | — | ao sair |

Uma partida vale até o `fim` ou até a mesma conta abrir **outra** (um jogador
só joga uma coisa por vez): depois disso, as rotas dela respondem
`410 {"erro":"partida encerrada"}`.

As rotas da conta do jogador (`POST /v1/contas`, `/v1/eu/confirmar`,
`/v1/senha/esqueci` etc.) estão no [`/openapi.json`](/openapi.json).

## Os códigos de erro mais comuns

| status | quando |
|---|---|
| `400` | JSON inválido, campo desconhecido ou valor fora da regra (a mensagem diz qual) |
| `401` | sem chave/token, chave inválida, token do jogador vencido |
| `403` | sem permissão (ex.: troca pelo navegador de outra origem; e-mail do jogador não confirmado: `codigo: "email_nao_confirmado"`) |
| `404` | jogo não existe, ou não publicado e você não é testador |
| `409` | conflito (ex.: prova fora do prazo) |
| `410` | partida encerrada (houve `fim` ou a conta abriu outra partida) |
| `429` | limite por IP; espere um minuto |
| `5xx` | erro nosso; tente de novo com espera |


---

<!-- https://developers.plicflix.com/docs/VITRINE.md -->

# A vitrine: como o seu jogo aparece no app

A vitrine é tudo o que o jogador vê **antes** de jogar: o destaque da tela
inicial, o cartão nas fileiras e a página do jogo (no estilo Netflix em cima e
Steam embaixo: galeria, "Sobre este jogo", avaliações, servidor ao vivo).

Você monta tudo no painel do developers, na aba **Vitrine** (textos) e na aba
**Imagens e vídeo** (arquivos). A aba **Como vai ficar** mostra a prévia no
app. Por API, os textos também podem ser editados com
`PUT /v1/parceiro/jogos/{slug}` ([API](API)).

## Onde cada coisa aparece

| peça | onde aparece |
|---|---|
| banner | o destaque da tela inicial e o topo da página do jogo (no celular, enquadrado no centro) |
| logo | por cima do banner, no lugar do nome |
| pôster | o cartão das fileiras ("Em alta", "Novidades", gêneros) e a busca |
| capturas | a galeria da página do jogo |
| trailer | o primeiro item da galeria |
| frase de chamada | debaixo do logo, no destaque e na página |
| descrição curta | o cartão expandido e a busca |
| "Sobre o jogo" | a seção de texto da página |
| cor | o fundo enquanto as imagens carregam |

## A qualidade mínima dos arquivos

Cada arquivo é conferido **no envio**, pelo conteúdo (não pela extensão). Se
estiver fora do padrão, o painel diz exatamente o que corrigir (ex.: "Captura
de tela recusado: a proporção é 1.68:1; precisa ser 16:9").

| peça | formatos | tamanho mínimo | proporção | peso máximo | outra regra |
|---|---|---|---|---|---|
| **Banner** | JPG, PNG, WebP | 1920×700 | **2:1 ou mais larga** | 8 MB | **sem texto nem logo** (o app põe o seu logo por cima); deixe o centro com o mais importante |
| **Pôster** | JPG, PNG, WebP | 600×900 | 2:3 (±4%) | 5 MB | pode ter o nome do jogo |
| **Logo** | PNG, WebP | 600 de largura, 120 de altura | livre | 3 MB | **fundo transparente** (conferido) |
| **Captura** | JPG, PNG, WebP | 1280×720 | 16:9 (±4%) | 8 MB | de 3 a 12; imagens reais do jogo |
| **Trailer** (opcional) | MP4 (H.264) ou WebM (VP8, VP9, AV1) | 1280×720 | 16:9 (±5%) | 200 MB | de 15 s a 3 min |

Os arquivos ficam na CDN do plicflix (`https://midia.plicflix.com`). Isso é só
a vitrine: **o jogo em si nunca fica com o plicflix.** Trocar um arquivo apaga
o anterior.

## Os textos

| campo | mínimo para enviar à revisão | máximo |
|---|---|---|
| nome | — | 60 |
| frase de chamada | 20 letras | 120 |
| descrição curta | 40 letras | 300 |
| "Sobre o jogo" | 300 letras | 8000 (parágrafos separados por linha em branco) |
| gêneros | 1 | 6, cada um com até 30 letras |
| tags | — | 20, cada uma com até 30 letras |
| estúdio | preenchido | — |
| classificação indicativa | obrigatória | `L`, `10`, `12`, `14`, `16` ou `18` |
| plataformas | — | `web`, `android`, `ios`, `desktop`, `tv` |
| cor | — | `#rrggbb` |

**Classificação indicativa:** use a do seu jogo segundo a ClassInd. Jogos com
apostas, cassino ou conteúdo adulto são **18**.

## Dicas que aprovam mais rápido

- **Banner:** a cena mais bonita do jogo, sem texto, com espaço livre à
  esquerda (é onde entram o logo e os botões).
- **Capturas:** do jogo de verdade, no tamanho real, sem molduras de celular.
- **Frase de chamada:** o que o jogador **faz** no jogo, numa frase.
- **Trailer:** os primeiros 5 segundos já mostrando o jogo.


---

<!-- https://developers.plicflix.com/docs/MOTORES.md -->

# Motores e casos especiais

O plicflix abre a **versão web** do seu jogo. O que muda de um motor para
outro é só **como** o jogo fala com o SDK do navegador (`window.Plicflix`). A
troca do token no servidor ([SDK](SDK#4-entrada-o-jogador-já-chega-logado)) é
igual para todos.

| o seu jogo | o caminho |
|---|---|
| JavaScript/TypeScript (Phaser, PixiJS, Three.js, Babylon.js, Construct, PlayCanvas, puro…) | chame `Plicflix.*` direto — [SDK](SDK) |
| **Unity WebGL** | [Unity](#unity-webgl) |
| **Godot 4 (Web)** | [Godot](#godot-4-web) |
| Flutter web | [Flutter web](#flutter-web) |
| outro motor que exporta para a web e fala com JavaScript (Defold, GameMaker HTML5, Bevy/wasm, Emscripten…) | chame as funções do `window.Plicflix` pela ponte JS do motor, ou fale o [protocolo de mensagens](SDK#12-o-protocolo-de-mensagens-sem-o-sdk-em-javascript) |
| **sem servidor** (só arquivos estáticos) | [Jogo sem servidor](#jogo-sem-servidor) |
| só app nativo (Android, iOS, PC), sem versão web | [Ainda não](#jogos-só-nativos) |

## Antes de tudo: exporte sem threads

Unity com "Multithreading" e Godot com "Thread Support" precisam de
`SharedArrayBuffer`, que exige os cabeçalhos COOP/COEP — e eles **não
funcionam** com o jogo dentro de um iframe de outro site (o app do plicflix).
Exporte **sem threads**:
- **Unity:** Player Settings → WebGL → Publishing Settings → *Enable
  Multithreading* desligado (é o padrão).
- **Godot 4.3+:** Exportar → Web → *Thread Support* desligado. (Godot 4.0–4.2
  sempre usa threads na web: use 4.3 ou mais novo.)

## Recarregar a página

Depois da primeira entrada, o token já foi usado: se o jogador recarregar a
página, `entrar` falha. Nesse caso, use a **sessão que o seu servidor já
abriu** (o cookie): peça ao seu servidor "quem sou eu" (ex.: `GET /api/eu`) e
siga. Só mostre erro se não houver sessão. Os exemplos abaixo mostram onde.

## Unity WebGL

Arquivos prontos:
- [`Plicflix.jslib`](/sdk/unity/Plicflix.jslib?baixar=1) → `Assets/Plugins/WebGL/Plicflix.jslib`
- [`Plicflix.cs`](/sdk/unity/Plicflix.cs?baixar=1) → `Assets/Plicflix/Plicflix.cs`

Passos:
1. No seu template WebGL (`Assets/WebGLTemplates/<seu>/index.html`), antes do
   loader do Unity: `<script src="plicflix.js"></script>`, e copie o
   [`plicflix.js`](/sdk/plicflix.js?baixar=1) para a pasta do template.
2. Na primeira cena, crie um GameObject chamado **`Plicflix`** e adicione o
   componente `Plicflix`.
3. No seu código:

```csharp
void Start() {
    if (!Plicflix.I.Dentro) { /* aberto fora do plicflix: o seu login de sempre */ return; }
    Plicflix.I.Progresso(20, "Entrando…");
    Plicflix.I.AoEntrou += json => {               // a resposta do SEU servidor
        // JsonUtility.FromJson<MinhaResposta>(json) …
        Plicflix.I.Pronto();
    };
    Plicflix.I.AoFalhou += erro => StartCoroutine(UsarSessaoOuErro());   // recarregou? a sessão já existe
    Plicflix.I.AoSairDoJogo += terminou => { SalvarProgresso(); terminou(); };
    Plicflix.I.AoPedirIrPara += destinoJson => { /* leve o jogador */ Plicflix.I.FoiPara(true); };
    Plicflix.I.Entrar("/api/plicflix/entrar");     // o seu servidor troca o token
}
IEnumerator UsarSessaoOuErro() {
    using var r = UnityEngine.Networking.UnityWebRequest.Get("/api/eu");   // o cookie vai junto
    yield return r.SendWebRequest();
    if (r.result == UnityEngine.Networking.UnityWebRequest.Result.Success) Plicflix.I.Pronto();
    else Plicflix.I.Erro("Não foi possível entrar. Abra o jogo de novo pelo plicflix.");
}
// a cada troca de cena:
Plicflix.I.Onde("{\"texto\":\"Floresta\",\"area\":\"mundo/floresta\"}");
```

No Editor (fora da web), todas as chamadas são ignoradas e `Dentro` é
`false`: o jogo roda normal.

**O servidor:** o jogo Unity é servido pelo seu servidor web; a rota
`/api/plicflix/entrar` e os cabeçalhos (`frame-ancestors`, cookie) são os do
[SDK](SDK#5-deixar-o-plicflix-abrir-o-seu-jogo). Sem servidor próprio, use
`Plicflix.I.Jogador()` (veja [abaixo](#jogo-sem-servidor)).

## Godot 4 (Web)

Arquivo pronto: [`plicflix.gd`](/sdk/godot/plicflix.gd?baixar=1).

1. **Projeto → Exportar → Web → Head Include:** `<script src="plicflix.js"></script>`,
   e copie o [`plicflix.js`](/sdk/plicflix.js?baixar=1) para a pasta exportada.
2. **Projeto → Configurações do projeto → Autoload:** adicione o `plicflix.gd`
   com o nome **`Plicflix`**.
3. No seu jogo:

```gdscript
func _ready():
    if not Plicflix.dentro():
        return  # fora do plicflix
    Plicflix.progresso(20, "Entrando…")
    Plicflix.ao_sair = func(): salvar_progresso()
    Plicflix.ao_ir_para = func(destino): return levar_ate(destino)   # true/false
    var r = await Plicflix.entrar("/api/plicflix/entrar")           # {} se falhou
    if r.is_empty():
        # recarregou a página? a sessão (cookie) já existe: pergunte ao seu servidor
        # (ex.: HTTPRequest em /api/eu); sem sessão, Plicflix.erro("…") e pare aqui
        pass
    Plicflix.pronto()
    Plicflix.onde({"texto": "Floresta", "area": "mundo/floresta"})
```

Fora da web (`OS.has_feature("web")` falso), tudo é ignorado.

## Flutter web

```dart
import 'dart:js_interop';
import 'dart:js_interop_unsafe';

final plicflix = globalContext['Plicflix'] as JSObject?;
bool get dentro => plicflix?.callMethod<JSBoolean>('dentro'.toJS).toDart ?? false;
void pronto() => plicflix?.callMethod('pronto'.toJS);
void onde(String texto) => plicflix?.callMethod('onde'.toJS, texto.toJS);
Future<void> entrar(String url) async =>
    (plicflix!.callMethod<JSPromise>('entrar'.toJS, url.toJS)).toDart;
```

Carregue o `plicflix.js` no `web/index.html`, antes do `flutter_bootstrap.js`.

## Jogo sem servidor

Se o seu jogo é só arquivos estáticos (sem um servidor seu para guardar a
chave), use `Plicflix.jogador()` no lugar do `Plicflix.entrar`:

```js
if (Plicflix.dentro()) {
  const { jogador } = await Plicflix.jogador();   // { id: "pf_…", nome: "Ana" }
  carregarSave(localStorage.getItem("save:" + jogador.id));
  Plicflix.aoSair(() => localStorage.setItem("save:" + jogador.id, gerarSave()));
  Plicflix.pronto();
}
```

Como funciona: a página troca o token direto na API do plicflix
(`POST https://api.plicflix.com/v1/ingresso/navegador`), sem chave. Só vale se
o pedido vier **da origem cadastrada** do seu jogo. Recarregar a página devolve
o mesmo jogador (fica guardado na aba).

**O limite:** tudo o que roda no navegador pode ser forjado por quem sabe
mexer. Serve para mostrar o nome e guardar progresso local. **Não use** para
moedas, ranking, compras ou qualquer coisa de valor — para isso, um servidor
com a troca normal.

O resto da integração (`frame-ancestors`, `pronto`, `aoSair`, `onde`) é igual.
Hospedagens estáticas: o cabeçalho vai num arquivo de configuração —
Netlify/Cloudflare Pages: `_headers` com
`/*` → `Content-Security-Policy: frame-ancestors 'self' https://plicflix.com`;
Vercel: `headers` no `vercel.json`. (GitHub Pages não deixa mudar cabeçalhos:
não serve.)

## Jogos só nativos

Hoje o plicflix abre jogos pela web (no app do celular, por uma WebView). Um
jogo que só existe como app Android/iOS ou executável de PC **ainda não**
consegue entrar. Se o seu motor exporta para a web (Unity, Godot, Defold,
GameMaker…), exporte e siga esta página. Jogo em nuvem (streaming de vídeo do
jogo rodando num servidor) está nos planos; fale com `suporte@plicflix.com` se
for o seu caso.


---

<!-- https://developers.plicflix.com/docs/SOCIAL.md -->

# Amigos, "onde estou" e privacidade

Os jogadores do plicflix têm **amigos** (adicionados pelo código de amigo), e
cada um escolhe quem vê onde ele está: **amigos** (padrão), **todos** ou
**ninguém**. O seu jogo participa de duas formas — ambas opcionais, ambas
recomendadas:

1. **Contar onde o jogador está** com `Plicflix.onde({ texto, area, ponto })`.
2. **Levar o jogador até um amigo** com `Plicflix.aoIrPara(fn)`.

## O que acontece com o "onde"

| campo | quem vê | para quê |
|---|---|---|
| `texto` (até 60) | o próprio jogador (na bolha) e os amigos, se a privacidade deixar | "Ana — Jogando Ilha das Luzes · Praia do Norte" |
| `area` (até 60; `a-z 0-9 / _ . -`) | ninguém, por enquanto | agrupar (quantos estão na praia) |
| `ponto` (objeto de até 1 KB) | **só o seu jogo** | volta no `aoIrPara` |

E ainda: o último "onde" aparece na fileira **"Continuar jogando"** da tela
inicial, em qualquer aparelho ("📍 Praia do Norte · há 2 h").

## "Ir até" e "Chamar para cá"

- **Ir até:** o jogador toca em "Ir até" num amigo (na tela Amigos ou na
  bolha). O app abre o jogo do amigo (ou, já dentro dele, manda o pedido) e o
  **seu** `aoIrPara` recebe o destino.
- **Chamar para cá:** o amigo recebe um aviso na bolha, com o botão "Ir". Isso
  libera o "ir até" por 24 h, mesmo com a privacidade fechada.

O destino que o seu jogo recebe:

```js
{ jogador_id: "pf_…",   // o código de QUEM ESTÁ LÁ, no SEU jogo
  jogador: "Ana",       // o apelido
  texto: "Praia do Norte", area: "ilha/praia",
  ponto: { x: 10, y: 4 },  // o que o seu jogo mandou no onde (pode faltar)
  jogo: "ilha-das-luzes" }
```

**Regra de segurança:** não teletransporte pelo `ponto` que veio do navegador.
Mande o `jogador_id` ao **seu servidor**, ache lá esse jogador online e leve
até a posição **real** dele, se o lugar permitir. Devolva `true`, `false` ou
`{ ok: false, motivo: "Ela está numa área particular." }` — o motivo aparece
para o jogador. Detalhes: [SDK](SDK#10-amigos-ir-até-e-chamar-para-cá).

## O que o seu jogo **nunca** recebe

O e-mail, a lista de amigos, o código de amigo do plicflix, dados de
pagamento, país. Do jogador chegam só o `id` (diferente em cada jogo, para
estúdios não cruzarem quem é quem) e o apelido.


---

<!-- https://developers.plicflix.com/docs/REGRAS.md -->

# Regras: taxa, revisão, repasse e reclamações

## A taxa de entrada

- **Valor:** R$ 499,00, uma vez por estúdio. Cobre o SDK, a avaliação inicial
  dos jogos e o suporte.
- **Quando:** a fatura nasce no cadastro e vence em 7 dias. Enquanto estiver
  em aberto, a área mostra só a fatura, a documentação e o SDK.
- **Como pagar:** enquanto o pagamento on-line não está ligado, responda ao
  e-mail da fatura (ou escreva para `suporte@plicflix.com`) com o número dela:
  mandamos Pix ou boleto. Pago, você recebe o e-mail "Pagamento confirmado" e a
  área libera na hora.

## A revisão

- Você envia pelo painel quando a lista de conferência está sem pendências.
- A equipe abre o jogo, joga, confere a integração e a vitrine.
- **Prazo:** em geral até 3 dias úteis. A resposta chega por e-mail.
- **Publicado:** o jogo entra no catálogo para todos os assinantes.
- **Recusado:** o e-mail e o painel dizem exatamente o que corrigir; corrija e
  envie de novo.
- O que costuma recusar: entrada que pede login, tela de carregamento que não
  sai, "Sair" que não salva, imagens fora do padrão ou que não são do jogo,
  classificação indicativa errada, servidor instável.

## Repasse

**60% do líquido de cada assinante vai para os jogos que ELE jogou, na
proporção do tempo ativo em cada um.**

```
líquido  = valor pago − impostos − taxa da loja (Apple/Google) − taxa do meio de pagamento
fundo    = 60% × (líquido − custo de nuvem usado por esse assinante, se houver)
parte(j) = fundo × tempo_ativo(j) / tempo_ativo(todos os jogos dele no mês)
```

- **Cada assinante divide só o próprio dinheiro.** Quem joga 100 horas de
  outro jogo não tira nada da parte que um assinante seu gerou para você.
- **Mínimo de 5 minutos** no mês para o jogo entrar na divisão daquele
  assinante.
- **Quem mede o tempo é o app do plicflix**, nunca o jogo: só conta depois do
  seu `pronto()`, com a tela visível e o jogador ativo; um jogador só acumula
  tempo em um jogo por vez.
- **Extrato:** `GET /v1/parceiro/repasses` ([API](API)).
- Exemplo: o assinante pagou R$ 29,90 e sobraram R$ 23,92 de líquido; o fundo
  é R$ 14,35. Ele jogou 3 h do jogo A e 1 h do B: A recebe R$ 10,76; B,
  R$ 3,59.

## Reclamações

Se os jogadores reclamam do jogo, abre um **caso**. Para a regra não virar
arma de concorrente:

1. **Só reclama quem jogou:** pelo menos 30 minutos daquele jogo no mês; uma
   reclamação por jogador, por jogo, por mês.
2. **O caso abre por volume:** 3 reclamações válidas ou 2% dos jogadores do
   mês, o que for maior.
3. **Prazo de 48 horas úteis** para corrigir e mandar a prova da correção
   (sábado e domingo não contam; fuso de Brasília).
4. **O valor do mês fica retido, não perdido**, enquanto o caso está aberto ou
   em análise.

```
aberto ──(prova dentro do prazo)──▶ em análise ──(equipe aceita)──▶ corrigido → recebe tudo
   │                                     └──(equipe recusa)───────▶ perdido   → perde o mês
   └──(prazo venceu sem prova)──────────────────────────────────────▶ perdido
```

- **Você é avisado por e-mail** quando um caso abre, com o prazo e os números.
- **A prova:** `POST /v1/parceiro/casos/{id}/prova {"prova":"…"}` ([API](API))
  ou respondendo ao e-mail do caso. Diga o que mudou e como conferir.
- Motivos que o jogador escolhe: `nao_abre`, `trava`, `trapaca`,
  `conteudo_improprio`, `cobranca`, `outro`.
- Perder o mês não tira o jogo do catálogo.

## Suspensão

A equipe pode suspender um estúdio (os jogos saem do catálogo e a chave para
de funcionar) em caso de fraude no tempo de jogo, conteúdo ilegal, risco aos
jogadores ou falta de pagamento. Você recebe um e-mail e pode responder para
resolver.


---

<!-- https://developers.plicflix.com/docs/TERMOS.md -->

# Termos do plicflix developers

*Versão inicial, de 2 de novembro de 2026. Ao criar a conta de desenvolvedor,
você aceita estes termos em nome do estúdio.*

1. **O que é.** O plicflix é uma plataforma de assinatura que abre jogos de
   estúdios parceiros por cima do seu app. O plicflix não hospeda o jogo: ele
   roda nos servidores do estúdio.
2. **A conta.** Você responde pelos dados do cadastro (nome, CPF ou CNPJ,
   e-mail) e pela guarda da senha e da chave de integração (`pk_…`). Avise
   `suporte@plicflix.com` se suspeitar que vazaram, e gere uma chave nova.
3. **A taxa de entrada** é paga uma vez por estúdio, cobre o acesso ao SDK, a
   avaliação inicial e o suporte, e não é devolvida depois que a área é
   liberada.
4. **O jogo.** Você garante que tem os direitos do jogo e de toda a vitrine
   (imagens, vídeos, textos, marcas), que a classificação indicativa está
   correta e que o jogo cumpre a lei brasileira (incluindo o Estatuto da
   Criança e do Adolescente e a LGPD). Jogos com apostas ou conteúdo adulto são
   classificados como 18.
5. **A revisão.** O plicflix pode publicar, recusar com motivo, tirar do
   catálogo ou desativar jogos, e destacar os que escolher.
6. **Os dados do jogador.** O estúdio recebe só o código do jogador (`pf_…`,
   diferente em cada jogo) e o apelido. Use só para operar o jogo; não tente
   descobrir a identidade real nem cruzar com outros jogos.
7. **O repasse** segue as [Regras](REGRAS): 60% do líquido de cada assinante,
   dividido pelo tempo ativo medido pelo app do plicflix, com os casos de
   reclamação podendo reter ou cancelar o valor do mês.
8. **Proibido:** inflar o tempo de jogo de forma artificial, contas falsas,
   coletar dados pessoais dos jogadores sem base legal, malware, burlar a bolha
   ou a tela de carregamento do plicflix, e cobrar dentro do jogo de forma
   enganosa.
9. **Suspensão.** Descumprir estes termos pode levar à suspensão do estúdio e à
   retenção dos repasses ligados à infração.
10. **Mudanças.** Estes termos podem mudar; avisamos por e-mail com 30 dias de
    antecedência quando a mudança afetar o repasse.
11. **Contato:** `suporte@plicflix.com`. Foro: a comarca da sede do plicflix.