> ## Documentation Index > Fetch the complete documentation index at: https://developers.googa.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Métricas agregadas de engajamento de leitura, por parceiro e período > Suporte aos indicadores prometidos na proposta (DAU/MAU do ritual diário, take-rate, retenção) — sempre agregado ao nível do parceiro, nunca por assinante. Nenhuma resposta desta rota inclui `subscriber_id` em nenhum nível; ver [Privacidade & LGPD](/security/lgpd) para o racional. **Pré-requisito ainda não desenhado em outra página:** para calcular qualquer coisa "por parceiro", as tabelas de leitura (`reading_progress` e afins) precisam de uma coluna `partner_id` — hoje elas não distinguem um leitor que entrou pelo app oficial de um que entrou via SSO de um parceiro. Isso é mencionado como necessidade genérica em [Isolamento multi-tenant](/architecture/supabase-auth-model#capacidades-nativas-do-supabase), mas o backfill/migração real dessa coluna não está feito nem desenhado em detalhe — este endpoint está, portanto, mais atrás no roadmap do que os demais desta especificação, que só precisam do `subscriber_id` já resolvido pela Platform API. `ending_distribution` omite qualquer combinação novela/final com menos de `minimum_cohort_size` leitores no período — supressão de cohort pequeno para reduzir risco de reidentificação, não um limite arbitrário de exibição. ## OpenAPI ````yaml /novelai/openapi.yaml get /analytics/engagement openapi: 3.1.0 info: title: Googa NovelAI API version: 1.0.0 summary: >- API específica de produto para NovelAI — catálogo de novelas seriadas, capítulos liberados pelo drip diário, progresso de leitura por assinante e os finais disponíveis. Não repete Entitlements, Billing ou SSO — isso é resolvido uma única vez pela Platform API (ver aba API Platform); esta especificação cobre apenas o que é específico de conteúdo/leitura do NovelAI. description: >- Hoje o catálogo, os capítulos e o progresso de leitura são consumidos diretamente pelo app oficial (Web/PWA — não há apps nativos) contra o Supabase do projeto "Novel", via Row Level Security. Esta especificação é um **contrato proposto, ainda não implementado**: descreve como um sistema terceiro (como o app da operadora) leria esses mesmos dados sem acesso direto ao banco. Ver [Modelo de autenticação sobre Supabase](/architecture/supabase-auth-model) para o desenho de autenticação completo. Esta é uma API **somente leitura** do ponto de vista do parceiro: nenhum endpoint aqui escreve em `reading_progress`, `subscriptions` ou qualquer outra tabela de domínio do leitor — isso continua sendo decisão do app oficial e, para os aspectos de assinatura/plano, da Platform API (`POST /entitlements`). O parceiro lê catálogo, capítulos liberados e progresso; não empurra leitura. NovelAI e NovelAudio compartilham o mesmo projeto Supabase ("Novel") e o mesmo domínio `api.novelai.com.br` — os recursos de streaming e player de áudio (voz, posição de reprodução, download offline) são documentados na aba NovelAudio, não aqui, ainda que fisicamente sejam a mesma API. contact: name: Googa — Suporte a parceiros email: developers@googa.com.br license: name: Uso restrito — ver Política de Uso da API url: https://developers.googa.com.br/security/api-usage-policy servers: - url: https://api.novelai.com.br/v1 description: Produção (proposto) - url: https://sandbox.novelai.com.br/v1 description: Sandbox (proposto) — catálogo fictício, sem impacto em billing real security: - partnerOAuth2: [] tags: - name: Catalog description: Catálogo público de categorias e novelas — metadados, sem gate de drip. - name: Chapters description: Capítulos de uma novela e seu estado de liberação (drip) por assinante. - name: Progress description: Progresso de leitura consolidado por assinante, entre novelas. - name: Choices description: >- Finais disponíveis de uma novela — só aparecem quando o drip libera o último capítulo. - name: Analytics description: >- Métricas agregadas de engajamento por parceiro — nunca por leitor identificável. paths: /analytics/engagement: get: tags: - Analytics summary: Métricas agregadas de engajamento de leitura, por parceiro e período description: >- Suporte aos indicadores prometidos na proposta (DAU/MAU do ritual diário, take-rate, retenção) — sempre agregado ao nível do parceiro, nunca por assinante. Nenhuma resposta desta rota inclui `subscriber_id` em nenhum nível; ver [Privacidade & LGPD](/security/lgpd) para o racional. **Pré-requisito ainda não desenhado em outra página:** para calcular qualquer coisa "por parceiro", as tabelas de leitura (`reading_progress` e afins) precisam de uma coluna `partner_id` — hoje elas não distinguem um leitor que entrou pelo app oficial de um que entrou via SSO de um parceiro. Isso é mencionado como necessidade genérica em [Isolamento multi-tenant](/architecture/supabase-auth-model#capacidades-nativas-do-supabase), mas o backfill/migração real dessa coluna não está feito nem desenhado em detalhe — este endpoint está, portanto, mais atrás no roadmap do que os demais desta especificação, que só precisam do `subscriber_id` já resolvido pela Platform API. `ending_distribution` omite qualquer combinação novela/final com menos de `minimum_cohort_size` leitores no período — supressão de cohort pequeno para reduzir risco de reidentificação, não um limite arbitrário de exibição. operationId: getEngagementAnalytics parameters: - name: period_start in: query required: true schema: type: string format: date - name: period_end in: query required: true schema: type: string format: date responses: '200': description: Relatório agregado do período. content: application/json: schema: $ref: '#/components/schemas/EngagementReport' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' components: schemas: EngagementReport: type: object properties: period_start: type: string format: date period_end: type: string format: date active_readers: type: integer description: >- Assinantes distintos deste parceiro com alguma atividade de leitura no período. avg_chapters_read_per_active_reader: type: number format: float completion_rate: type: number format: float description: >- Proporção de novelas iniciadas no período que chegaram a um final escolhido. ending_distribution: type: array items: type: object properties: novel_id: type: string choice_id: type: string label: type: string count: type: integer description: Omite combinações com menos de `minimum_cohort_size` leitores. minimum_cohort_size: type: integer example: 20 generated_at: type: string format: date-time Error: type: object description: >- Mesmo formato de erro (estilo OAuth2, RFC 6749 §5.2) usado pela Platform API. properties: error: type: string example: invalid_request error_description: type: string example: Novela inexistente ou removida do catálogo responses: BadRequest: description: Parâmetros de requisição inválidos. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Credenciais ausentes, inválidas ou expiradas. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: partnerOAuth2: type: oauth2 description: >- Client credentials — emitido **uma única vez**, de forma centralizada, pela Platform API (`POST https://api.googa.com.br/v1/oauth2/token`, ver aba API Platform). Este domínio (`api.novelai.com.br`) só *valida* o token — via a chave pública do projeto Supabase "Platform" — nunca emite um token próprio. Isso evita duplicar a verificação de `client_id`/`client_secret` em três projetos Supabase diferentes: o parceiro autentica uma vez, e o mesmo token (com os escopos certos) funciona em qualquer domínio de produto. Ver "Roteamento cross-projeto" em [Modelo de autenticação sobre Supabase](/architecture/supabase-auth-model#partner-gateway-a-camada-que-conecta-as-duas-pontas). flows: clientCredentials: tokenUrl: https://api.googa.com.br/v1/oauth2/token scopes: novelai:catalog:read: Ler catálogo (novelas e categorias) novelai:chapters:read: Ler capítulos e estado de liberação por assinante novelai:progress:read: Ler progresso de leitura consolidado por assinante novelai:choices:read: Ler finais disponíveis por assinante novelai:analytics:read: Ler métricas agregadas de engajamento ````