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 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 de destino, cada um com um seletor dinâmico de múltipla seleção. Editar uma campanha (ação do lápis) abre o assistente descrito abaixo no modo de edição; excluir exige confirmação e não pode ser desfeito.

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 utilizadas") e um link "🔒 Fazer upgrade" para Assinatura.

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: enquanto você preenche uma etapa, suas 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ê 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 a perda do 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 de fato — um segundo tipo, "Publicidade em rede", existe no código como uma opção reservada para uso futuro, mas não pode ser selecionado na interface atualmente. Clicar em Próximo avança para a etapa seguinte; esta etapa não faz chamadas ao servidor por si só, pois nada é criado até a Etapa 2. No modo de edição, toda esta etapa é pulada — o assistente abre diretamente na Etapa 2, com o tipo da campanha existente já definido e sem possibilidade de alteração.

Etapa 2 — Configurações da campanha

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

• Chave de Status da campanha — apenas no modo de edição. Alterna entre Ativa e Pausada (com uma caixa de diálogo de confirmação em ambos os 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 dos criativos está ativo — caso contrário, a ativação será 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 da chave não terá efeito.
• 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", pois 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 arredondados selecionáveis; o padrão é Média.
• Início da campanha — "Imediato" ou uma data específica. Se você escolher uma data, ela não poderá ser anterior à data de hoje. No entanto, essa verificação é ignorada no modo de edição se você não tiver alterado a data que já estava 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 verificação de que a data de término seja posterior à data de início.

Bloqueio de campos enquanto a campanha estiver ativa: quando uma campanha está Ativa, você não pode mais alterar a Marca, o App a promover nem a configuração de Data de início/Imediato — esses campos ficam desabilitados, com uma breve nota 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 pausá-la (pela chave de status).

Ao salvar (no modo de criação, Salvar e próximo; 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. Somente após o sucesso da chamada de API esses dados são gravados no contexto compartilhado do assistente.

Etapa 3 — Segmentação

A segmentação consiste em duas subseções independentes que compartilham a mesma etapa e o mesmo 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. Você escolhe, por meio de listas com caixas de seleção, uma das opções:

• Todas as marcas — uma única caixa de seleção geral que permite que a campanha apareça em todas as marcas e apps que você possui, 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 individualmente ou marcar a caixa "Todos (incluindo futuros)" dessa marca para incluir todos os apps dela (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ê veja rapidamente a segmentação atual.

Regiões. Um seletor de múltipla seleção de países com o atalho "Selecionar todos", usado para restringir (ou não) os países em que a campanha é 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 com nome, descrito mais adiante neste guia — trata-se de uma seleção simples de países por campanha, sem nome, e não de um grupo salvo/reutilizável. (Se a lista dinâmica de países não for carregada do servidor, será usada uma lista alternativa menor, com 16 países. Por isso, as opções alternativas desse 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 permanecem locais até você clicar em Salvar (ou Salvar e próximo). Nesse momento, Veiculação e Regiões são persistidas por chamadas de API separadas e só entã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.

Adicionar novos criativos. O 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 exibido 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 nas demais áreas para unidades de anúncio).

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

Lista de criativos salvos. Os criativos já salvos aparecem acima do formulário de adição como 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 uma chave 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") — nos demais casos, é solicitada uma confirmação simples: "Ativar/Desativar criativo?".
• O botão de edição (lápis) abre um formulário na própria página para editar aquele criativo (nome, imagem e URL de destino — o tipo de anúncio não pode ser alterado), 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 inserido 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 de 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 da 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 uma chave de Status funcional (Ativa/Pausada) logo no topo — as mesmas regras de ativação da Etapa 2 se aplicam aqui (ela 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 é exibido como uma etiqueta somente leitura — você altera o status pela chave 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, pois cada etapa já foi salva ao longo do processo.

---