Campanhas (Promoção cruzada)

Campanhas é o mecanismo de promoção cruzada: permite anunciar um dos seus apps dentro de outro app seu, usando o mapeamento "Unidades de anúncio para espaços reservados de anúncio → Promoção cruzada" descrito em Detalhes do app.

A lista de campanhas

A página Campanhas (/campaigns) lista todas as campanhas que você criou em uma tabela: número da linha, Título, App de destino (nome e pacote, exibidos em duas linhas), Tipo de campanha (atualmente sempre "Promoção cruzada" — Publicidade em rede existe como conceito no seletor de tipo, mas não é oferecida como opção), Status e Prioridade (ambos exibidos como etiquetas coloridas e com opção de ordenação), Data de início, Data de término, Criado em, Atualizado em (os dois últimos também permitem ordenação) e Ações (Editar e Excluir).

Você pode filtrar a lista por Status da campanha, Prioridade ou Marca segmentada, cada um com um seletor dinâmico de múltipla seleção. Ao editar uma campanha (ação do lápis), você abre o assistente descrito abaixo no modo de edição; a exclusão pede confirmação antes e não pode ser desfeita.

O botão + Criar só fica disponível se o seu plano ainda permitir mais uma campanha de promoção cruzada (canCreateCampaign()). Se você atingir o limite de campanhas do plano, ele será substituído por um indicador de uso ("X/Y campanhas usadas") e um link "🔒 Fazer upgrade" para Assinatura.

Como criar ou editar uma campanha — o assistente

Clicar em + Criar (ou editar uma campanha existente) abre um assistente passo a passo. O assistente tem cinco etapas, não quatro — é fácil contar uma a menos porque a primeira etapa é pulada automaticamente ao editar uma campanha existente (o tipo não pode mais ser alterado depois que a campanha é criada). O padrão de "rascunho, depois salvar" é o mesmo em todo o assistente: conforme você preenche uma etapa, as alterações ficam apenas no estado local do componente dessa etapa. Nada é gravado no contexto compartilhado do assistente — e nada é persistido no servidor — até que você clique em um botão de salvamento e a chamada de API correspondente seja concluída com sucesso. Se você tentar sair com alterações não salvas, a confirmação "Você tem alterações não salvas. Tem certeza de que deseja sair?" (Sim, sair / Ficar) evita que você perca seu trabalho.

Etapa 1 — Selecionar o tipo de campanha

Um único cartão selecionável: Promoção cruzada ("Promova seus próprios apps para usuários dos seus outros apps"). Essa é a única opção disponível — um segundo tipo, "Publicidade em rede", existe no código como uma opção reservada para uso futuro, mas atualmente não pode ser selecionado na interface. Clicar em Avançar passa para a próxima etapa; esta etapa não faz chamadas ao servidor por conta própria, já que nada é criado até a Etapa 2. No modo de edição, esta etapa inteira é pulada — o assistente abre diretamente na Etapa 2, com o tipo da campanha existente já definido e bloqueado.

Etapa 2 — Configurações da campanha

Esta etapa serve tanto para criar a campanha (no primeiro salvamento, no modo de criação) quanto para editar suas configurações principais (no modo de edição). Campos:

• Alternância de Status da campanha — somente no modo de edição. Alterna entre Ativa e Pausada (com uma caixa de diálogo de confirmação nos dois casos: "Ativar campanha?" / "Pausar campanha?"). Ao tentar ativar uma campanha, antes de salvar, o sistema verifica se ela tem pelo menos um criativo e se pelo menos um desses criativos está ativo — caso contrário, a ação é bloqueada com a mensagem "Não é possível ativar a campanha — adicione pelo menos um criativo primeiro" ou "...pelo menos um criativo deve estar com o status ativo", e a alteração de status não será aplicada.
• Título da campanha — campo de texto obrigatório.
• Selecionar marca — lista suspensa obrigatória com suas marcas. Alterar a marca limpa o app selecionado em "App a promover", já que a lista de apps depende da marca.
• App a promover — lista suspensa obrigatória, preenchida com base na marca selecionada; fica desabilitada até que uma marca seja escolhida.
• Prioridade da campanha — Alta / Média / Baixa, exibidas como três botões selecionáveis em formato de cápsula; o padrão é Média.
• Início da campanha — "Imediato" ou uma data específica. Se você escolher uma data, ela não pode estar no passado (a validação usa a data de hoje como referência), exceto no modo de edição, em que essa validação é ignorada se você não tiver alterado a data já salva.
• Término da campanha — "Nenhum (Sem data de término)" ou uma data específica, com a mesma regra de não permitir datas no passado, além de uma validação para garantir que a data de término seja posterior à data de início.

Bloqueio de campos enquanto a campanha está ativa: quando uma campanha está Ativa, você não pode mais alterar a Marca, o App a promover nem a data de início/configuração de início imediato — esses campos ficam desabilitados com uma breve observação explicativa ("...não pode ser alterado enquanto a campanha estiver ativa"). Você ainda pode alterar o título, a prioridade, a data de término e pausar a campanha pelo controle de status.

Ao salvar (no modo de criação, Salvar e avançar; no modo de edição, Salvar), o título, o app de destino, o tipo de campanha, a prioridade, as datas de início/término calculadas e — no modo de edição — o status são enviados ao servidor. Na criação inicial, os dados existentes de veiculação/região retornados na resposta (se houver) são usados para preencher previamente o estado inicial da Etapa 3. Esses dados só são gravados no contexto compartilhado do assistente depois que a chamada de API é concluída com sucesso.

Etapa 3 — Segmentação

A segmentação consiste em duas subseções independentes que compartilham uma etapa e um botão Salvar: Veiculação (quais das suas marcas/apps devem exibir esta campanha) e Regiões (em quais países ela deve ser veiculada).

Veiculação. Por meio de listas com caixas de seleção, você escolhe entre:

• Todas as marcas — uma única caixa de seleção geral que permite exibir a campanha em todas as suas marcas e apps, incluindo os adicionados posteriormente.
• Marcas específicas — selecione uma ou mais marcas em uma lista rolável, cada uma com sua própria sublista de apps. Dentro de uma marca selecionada, você pode marcar apps individuais ou marcar a caixa "Todos (incl. futuros)" da própria marca para incluir todos os apps dessa marca (atuais e futuros), sem precisar selecioná-los um a um.

Um resumo atualizado de "Marcas selecionadas" e "Apps selecionados" é exibido como etiquetas acima das listas, para que você confira rapidamente a segmentação atual.

Regiões. Um seletor de múltiplos países com o atalho "Selecionar todos", usado para restringir (ou não) os países em que a campanha será veiculada. Se você não aplicar restrições, a campanha será veiculada em todas as regiões. Esse seletor de regiões é intencionalmente separado do recurso de Grupos de regiões nomeados, descrito mais adiante neste guia — trata-se de uma seleção simples de países, sem nome e específica para cada campanha, não de um grupo salvo/reutilizável. (Se a lista dinâmica de países não puder ser carregada do servidor, será usada uma lista alternativa menor, com 16 países. Por isso, as opções alternativas deste seletor são mais limitadas que as de Grupos de regiões.)

As duas subseções seguem o mesmo comportamento de rascunho/salvamento do restante do assistente: as alterações ficam locais até você clicar em Salvar (ou Salvar e avançar). Nesse momento, Veiculação e Regiões são persistidas com chamadas de API próprias e só depois são incorporadas ao estado compartilhado do assistente.

Etapa 4 — Criativos

É aqui que você faz o upload dos criativos de anúncio exibidos durante a veiculação da campanha.

Como adicionar novos criativos. Um formulário "Adicionar novos criativos" em formato de tabela permite adicionar uma ou mais linhas de uma vez (o link + Adicionar criativos adiciona outra linha em branco; o ícone de lixeira remove uma linha). Cada linha contém:

• Imagem — clique no quadrado vazio para fazer o upload. Formatos aceitos: JPEG, PNG, JPG, GIF, WebP; tamanho máximo de 10 MB. Arquivos fora desses critérios são rejeitados com um erro específico no próprio formulário (formato incorreto ou "Máx. 10 MB (X.XX MB)", mostrando o tamanho real).
• Nome — texto obrigatório.
• URL de destino — obrigatória; deve ser uma URL http:// ou https:// válida, verificada em tempo real enquanto você digita.
• Tipo de anúncio — intersticial, banner, nativo, recompensado ou appOpen (o mesmo conjunto de cinco formatos usado em outras partes para unidades de anúncio).

Clicar em Salvar e avançar (modo de criação) ou Salvar (modo de edição) valida todas as linhas não vazias, faz o upload de cada imagem e cria cada criativo pela API. Somente os criativos salvos com sucesso são adicionados à lista de salvos; se algum falhar, você verá quantos falharam e poderá tentar novamente. É necessário ter pelo menos um criativo para sair desta etapa no modo de criação.

Lista de criativos salvos. Os criativos já salvos aparecem acima do formulário de adição, em uma lista de cartões. Cada cartão mostra uma miniatura (clique para ampliar), nome, tipo de anúncio, URL de destino, uma etiqueta de status Ativo/Inativo com um controle de alternância, um botão de edição (lápis) e um botão de exclusão (lixeira).

• Desativar um criativo é bloqueado se ele for o único criativo ativo da campanha ("Pelo menos um criativo deve permanecer ativo") — em todos os outros casos, é solicitada apenas uma confirmação de "Ativar/Desativar criativo?".
• O botão de edição (lápis) abre um formulário de edição no próprio cartão daquele criativo (nome, imagem, URL de destino — o tipo de anúncio é fixo), com seus próprios botões Salvar/Cancelar.
• A exclusão exibe o aviso "Você não poderá desfazer esta ação!" antes de remover o criativo permanentemente.

Etapa 5 — Revisar campanha

Um resumo somente leitura de tudo o que foi informado nas Etapas 2–4: Status da campanha, Título, Tipo, Marca, App a promover, Prioridade, Data de início, Data de término, um resumo da Segmentação em uma linha (por exemplo, "Todas as marcas · Todos os apps" ou um detalhamento por marca), além das Regiões selecionadas (etiquetas ou "Todas as regiões") e a lista completa de Criativos com suas miniaturas, nomes, URLs de destino e etiquetas de tipo de anúncio.

Somente no modo de criação, esta etapa também tem um controle de Status (Ativa/Pausada) habilitado no topo — as mesmas regras de ativação da Etapa 2 se aplicam aqui (ele impede a ativação de uma campanha sem criativos ou sem nenhum criativo ativo, exibindo "Não é possível ativar a campanha"). No modo de edição, o status aparece como uma etiqueta somente leitura — você altera o status pelo controle da Etapa 2, não por aqui.

Clicar em Concluir retorna à lista de Campanhas. No modo de edição, você verá primeiro uma breve confirmação: "Campanha salva com sucesso"; no modo de criação, o retorno é direto, sem confirmação adicional, já que cada etapa foi salva ao longo do processo.

---