Apple Ads MCP

Apple Ads MCP

Apple Ads MCP é um servidor Model Context Protocol local-first para a Apple Ads Platform API v1. Ele fornece ao Codex, Claude e outros clientes MCP ferramentas tipadas para pesquisar, inspecionar e operar com segurança contas de publicidade na App Store.

O servidor é somente leitura por padrão. As credenciais permanecem na sua máquina, toda chamada com escopo de conta nomeia um perfil e uma conta de anúncios explícitos, e toda mutação exige uma prévia mais um recibo de uso único de curta duração.

Apple Ads MCP é um software de código aberto independente. Não é afiliado, endossado ou patrocinado pela Apple Inc. Apple Ads e App Store são marcas registradas da Apple Inc.

Início rápido

Instale o binário publicado com Homebrew no macOS ou Linux:

brew install zelentsov-dev/tap/apple-ads-mcp
apple-ads-mcp version

Crie um perfil local somente leitura. O comando armazena um caminho absoluto da chave privada; nunca cole a chave privada em um chat, issue, log ou repositório:

apple-ads-mcp config init
apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

Registre o servidor com um caminho absoluto do Homebrew para que aplicativos de desktop e extensões de IDE não dependam do PATH herdado do shell.

Codex:

codex mcp add apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
codex mcp list

Claude Code:

claude mcp add --scope user apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
claude mcp get apple-ads

Reinicie um aplicativo de desktop, sessão CLI ou extensão de IDE já em execução e inicie uma nova conversa. Uma primeira solicitação segura é:

Chame server_info e depois execute account_health para meu perfil, conta de anúncios e aplicativo explícitos. Não habilite gravações.

Outros iniciadores somente leitura úteis:

• "Liste os aplicativos que posso anunciar e explique quaisquer lacunas de elegibilidade."
• "Audite minha estrutura atual de campanhas do Apple Ads sem alterar nada."
• "Encontre oportunidades de palavras-chave e separe as evidências da Apple das suas inferências."

Versão atual

v0.3.6 é a versão atual. Ela adiciona diagnósticos acionáveis tipados, corrige a criação em massa de palavras-chave da Apple com IDs de correlação inteiros baseados em zero e um recibo agregado entre grupos, e reforça os contratos de leitura/consulta sem remover os id, filters legados ou entradas de nível superior de adGroupId em massa. Consulte as notas de versão e migração do v0.3.6.

A nomenclatura de arquivo final da versão v0.3.5, a confiança com escopo de fórmula do v0.3.4, a verificação de caminho exato do v0.3.3 e a integração em um comando do v0.3.2 permanecem intactas.

A otimização nunca é autônoma: o servidor não tem agendador e nunca altera gastos em segundo plano. Uma sessão somente leitura pode construir uma linha de base e um plano. Aplicar um plano ainda exige todos os portões de gravação, uma política nomeada ativa, um recibo, um relatório atualizado e verificação de desvio de inventário, além de verificação em nível de item.

A versão suporta os quatro posicionamentos da App Store expostos pela Apple:

• Search Results
• Search Tab
• Today Tab
• Product Pages

A disponibilidade de posicionamento ainda depende da conta selecionada, aplicativo, storefront, criativo e da resposta de elegibilidade da Apple. Um posicionamento indisponível é relatado como not_eligible; o servidor não tenta contornar a validação da Apple.

Palavras-chave e palavras-chave negativas são recursos de Search Results. A Platform API rejeita recursos explícitos de Ad para campanhas de Search Results, portanto esse posicionamento é operado por meio de sua campanha, grupo de anúncios, palavras-chave e configuração de página de produto; anúncios explícitos permanecem sujeitos à elegibilidade para os outros posicionamentos. Um criativo de Default Product Page é único por aplicativo e conta de anúncios, portanto os operadores devem consultá-lo e reutilizá-lo em vez de tentar criar uma duplicata.

O que ele pode fazer

Área	Ferramentas principais
Acesso e prontidão	auth_check, ad_accounts_list, ad_account_get, advertiser_resources_list, account_health
Aplicativos e storefronts	apps_search, apps_get, apps_eligibility, app_locale_details, supported_app_languages, app_store_geo_search
Inventário	campaigns_query, ad_groups_query, keywords_query, negative_keywords_query, ads_query, creatives_query, shared_budgets_query, campaign_inventory
Diagnósticos	motivos de rejeição, motivos de status de campanha, histórico de alterações, auditorias de conta e campanha
Pesquisa	sugestões de palavra-chave, frase, categoria, CPA-alvo, popularidade de pesquisa, participação de impressões
Relatórios	relatórios tipados de campanha, grupo de anúncios, anúncio, palavra-chave e termo de pesquisa
Operação de campanha	prévias de criar/atualizar, orçamento, países, agendamento, pausar e retomar
Operação de grupo de anúncios	prévias de criar/atualizar, agendamento, segmentação, Search Match, lance, limite de CPA, pausar e retomar
Palavras-chave	prévias de criar/atualizar em massa e individual de palavras-chave de segmentação/negativas, lance, pausar e retomar
Anúncios e criativos	prévias de criar/atualizar, pausar e retomar de criativos e anúncios tipados da App Store
Recomendações	prévias de leitura, aplicação e dispensa para orçamento diário e CPA-alvo
Otimização	políticas locais nomeadas, linhas de base de 28 dias, planos de aprendizado/ativos, prévia/aplicação/verificação compostas e histórico limitado
Orçamentos compartilhados	prévias tipadas somente LOC de criar/atualizar/atribuir/desatribuir com perfis de cobrança locais privados
Ciclo de vida	prévias de exclusão separadamente controladas de campanha, grupo de anúncios, palavra-chave, palavra-chave negativa, anúncio, criativo e orçamento compartilhado
Verificação	operations_inspect, operations_apply, operations_verify e leitura direta de recursos

Toda lista é limitada a 200 itens e usa paginação next. As respostas incluem texto conciso mais structuredContent do MCP; envelopes brutos da Apple e PII de contato de cobrança não são expostos.

Não há ferramenta de solicitação bruta, mutação de conta/delegação, agendador automático, superfície do Apple Maps ou suporte legado à Campaign Management API v5.

Modelo de segurança

Uma gravação só é possível quando todos os portões passam:

1. O usuário da API da Apple tem uma função de gravação compatível.
2. O servidor inicia com --allow-writes.
3. O perfil selecionado tem allowWrites: true.
4. Uma ferramenta especializada de *_preview valida a conta, o aplicativo, o storefront, o posicionamento, a moeda e o payload.
5. operations_apply recebe o mesmo recibo não expirado.
6. O inventário afetado ainda corresponde ao estado capturado durante a prévia.

Os recibos de prévia expiram após dez minutos e são de uso único para aplicação. Um tombstone limitado preserva o estado expirado explícito após o registro completo do recibo ser podado. Cada recibo de mutação vincula escopos canônicos de objetos para seus IDs de destino e retém impressões digitais exatas de leitura; criações e exclusões de pais também vinculam o inventário afetado e escopos de cascata limitados. Formas genéricas, em massa, de exclusão, recomendação, orçamento compartilhado e verificação de otimização para objetos sobrepostos, portanto, não podem ser despachadas simultaneamente. Inventários independentes de grupos de anúncios permanecem paralelos. Recibos em massa retornam estados em nível de item applied, failed ou unknown. Um recibo em massa de palavra-chave de segmentação pode conter vários grupos de anúncios por item enquanto ainda envia uma solicitação em massa da Apple. A Apple pode aceitar parcialmente um lote; o servidor nunca promete rollback. Se uma aplicação de otimização tiver um resultado não resolvido, uma receita de recuperação sanitizada permanece no histórico local somente do proprietário para que operations_verify possa reconciliar o recibo fornecido após uma reinicialização do processo ou evicção normal de prévia.

Prévias independentes do mesmo instantâneo de inventário intencionalmente divergem após a primeira aplicação. Coloque criações relacionadas de palavras-chave em uma única prévia em massa quando elas devem ser aplicadas como uma unidade; o servidor não enfraquece essa invariante de falha fechada.

Solicitações de mutação não são repetidas após um timeout. O resultado é committed_unverified, ou em nível de item unknown, até que operations_verify e leitura direta estabeleçam o estado real.

Operações de aplicação de recomendação exigem um maximumAmount explícito. A moeda da recomendação deve corresponder à conta de anúncios, o valor proposto deve permanecer abaixo do limite, e a recomendação mais a campanha promovida são relidas antes da aplicação.

Uma exclusão irreversível tem cinco portões adicionais: --allow-deletes, perfil allowDeletes: true, APPLE_ADS_ALLOW_DELETES=true somente de sessão, um nome de objeto ou texto de palavra-chave esperado exato e um recibo de exclusão especializado. Campanhas e pais devem estar PAUSED; o inventário em cascata é limitado e com hash; criativos não devem ter anúncios referenciados; orçamentos compartilhados não devem ter atribuições. DELETE nunca é repetido após um resultado ambíguo.

Validação da versão

A versão v0.3.6 exige a suíte de compatibilidade completa, testes de contrato stdio do MCP, testes de unidade e HTTP, o detector de corrida, análise estática, varreduras de vulnerabilidades e segredos e validação de distribuição. CI multiplataforma roda em macOS, Linux e Windows.

A confirmação em tempo de execução é um portão separado controlado pelo proprietário. Em 2026-08-31, a matriz somente leitura P2 do v0.3.6 e um fixture em massa de palavra-chave de segmentação PAUSED separadamente autorizado com 2 e 28 itens passaram contra a Apple Ads API v1. Ambos os recibos agregados aplicaram e verificaram cada ID de palavra-chave retornado diretamente; a campanha e o grupo de anúncios permaneceram PAUSED durante toda a aceitação de gravação.

A aceitação ao vivo anterior do v0.3.x confirmou linhas de base e planos de otimização somente leitura, criação e leitura de fixture PAUSED, atualizações de orçamento/lance/estratégia, pausar/retomar, verificações de desvio de recibo, verificação de itens e exclusão de campanhas, grupos de anúncios, palavras-chave e palavras-chave negativas descartáveis. Todos os fixtures retidos permaneceram PAUSED com gasto zero. Essa evidência histórica não substitui o novo portão de aceitação em massa/P2 do v0.3.6.

Caminhos dependentes de conta têm um limite de evidência explícito:

• Aplicação de plano de otimização ativo e MAX_CONVERSIONS permanecem verificados por teste automatizado até que uma campanha madura deliberadamente selecionada atenda aos requisitos mínimos de 14 dias de dados e aos portões de elegibilidade da Apple.
• Criação/atualização/atribuição/exclusão de orçamento compartilhado permanecem verificados por contrato e teste HTTP porque a conta de aceitação ao vivo usa PAYG; a Apple exige LOC.
• A exclusão de anúncio e criativo de Default Product Page é confirmada como not_eligible porque a Apple não permite que esses recursos sejam excluídos individualmente.

Esses limites não enfraquecem o modelo de segurança padrão: operações não suportadas ou insuficientemente evidenciadas falham fechadas e nunca se tornam respostas vazias bem-sucedidas.

Instalação

Plataforma	Homebrew	Arquivo do GitHub	Imagem OCI
macOS arm64 / amd64	Sim	.tar.gz	Somente contêiner Linux
Linux arm64 / amd64	Sim	.tar.gz	Sim
Windows arm64 / amd64	Não	.zip	Somente contêiner Linux

Homebrew

O tap oficial instala um binário de versão com checksum fixado:

brew install zelentsov-dev/tap/apple-ads-mcp

Atualize versões posteriores com:

brew update
brew upgrade apple-ads-mcp

GitHub release

Baixe o arquivo para sua plataforma em GitHub Releases. As versões incluem checksums SHA-256 e SBOMs SPDX.

Exemplo para Apple silicon:

curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.3.6/apple-ads-mcp_darwin_arm64_0.3.6.tar.gz
curl -LO https://github.com/zelentsov-dev/apple-ads-mcp/releases/download/v0.3.6/checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
tar -xzf apple-ads-mcp_darwin_arm64_0.3.6.tar.gz
sudo install -m 0755 apple-ads-mcp /usr/local/bin/apple-ads-mcp

Usuários do Windows devem verificar checksums.txt, extrair o ZIP correspondente e registrar o executável com seu caminho absoluto.

Imagem OCI

docker pull ghcr.io/zelentsov-dev/apple-ads-mcp:0.3.6

A imagem executa serve --stdio por padrão. Monte accounts.json e sua chave privada referenciada somente leitura.

Compilar a partir do código-fonte

git clone https://github.com/zelentsov-dev/apple-ads-mcp.git
cd apple-ads-mcp
go build -trimpath -o ./apple-ads-mcp ./cmd/apple-ads-mcp

Go 1.26.7 ou mais recente é necessário.

Configuração da API da Apple

O acesso à Apple Ads API é separado do acesso ao App Store Connect. Um Administrador da Conta de Apple Ads deve adicionar um usuário de API com a função apropriada. Prefira API Account Read Only até que mudanças de campanha sejam necessárias.

Gere um par de chaves ES256 localmente:

umask 077
openssl ecparam -name prime256v1 -genkey -noout -out apple-ads-private-key.pem
openssl ec -in apple-ads-private-key.pem -pubout -out apple-ads-public-key.pem
chmod 600 apple-ads-private-key.pem

Envie somente a chave pública no Apple Ads. Nunca cole a chave privada em uma conversa de agente, issue, log ou repositório. Depois que a Apple registrar a chave, registre o client ID, team ID e key ID mostrados na interface do Apple Ads.

Configurar

Crie um perfil interativamente:

apple-ads-mcp config init

O caminho de configuração padrão é ~/.config/apple-ads-mcp/accounts.json:

{
  "profiles": [
    {
      "name": "production-read-only",
      "clientId": "SEARCHADS.example-client-id",
      "teamId": "SEARCHADS.example-team-id",
      "keyId": "EXAMPLEKEY",
      "privateKeyPath": "/absolute/path/to/apple-ads-private-key.pem",
      "defaultAdAccountId": "123456789",
      "allowWrites": false,
      "allowDeletes": false
    }
  ]
}

Em sistemas POSIX, a configuração e a chave privada devem ser somente do proprietário:

chmod 600 ~/.config/apple-ads-mcp/accounts.json /absolute/path/to/apple-ads-private-key.pem

Valide a autenticação e descubra contas de anúncios acessíveis:

apple-ads-mcp auth doctor --profile production-read-only
apple-ads-mcp accounts discover --profile production-read-only

A precedência de configuração é --config, APPLE_ADS_MCP_CONFIG, o arquivo padrão e, em seguida, variáveis de ambiente de perfil único APPLE_ADS_*. As variáveis de perfil único suportadas são APPLE_ADS_PROFILE, APPLE_ADS_CLIENT_ID, APPLE_ADS_TEAM_ID, APPLE_ADS_KEY_ID, APPLE_ADS_PRIVATE_KEY_PATH, APPLE_ADS_AD_ACCOUNT_ID, APPLE_ADS_ALLOW_WRITES e APPLE_ADS_ALLOW_DELETES. Para um perfil baseado em arquivo, as variáveis de ambiente não concedem silenciosamente permissão persistente de gravação ou exclusão.

Conectar um cliente MCP

O servidor usa stdio e grava MCP JSON-RPC apenas em stdout:

apple-ads-mcp serve --stdio

Para clientes com CLI, prefira um caminho absoluto do binário.

Configuração global do Codex:

codex mcp add apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
codex mcp list

O Codex Desktop, o Codex CLI e a extensão do IDE compartilham a mesma configuração do host. Reinicie um cliente já em execução e abra uma nova conversa após adicionar o servidor.

Configuração do usuário do Claude Code:

claude mcp add --scope user apple-ads -- "$(brew --prefix)/bin/apple-ads-mcp" serve --stdio
claude mcp get apple-ads

A configuração do projeto Claude pode usar o .mcp.json do repositório, mas cada workspace/servidor pode permanecer pendente até que o usuário aprove. Reconecte-se de /mcp ou reinicie o Claude Code após a aprovação.

Configuração MCP genérica para clientes sem um comando de registro:

{
  "mcpServers": {
    "apple-ads": {
      "command": "apple-ads-mcp",
      "args": ["serve", "--stdio"]
    }
  }
}

Substitua apple-ads-mcp pelo caminho absoluto do executável quando o cliente não herdar o PATH do Homebrew ou do shell. No Apple silicon, o caminho padrão do Homebrew é /opt/homebrew/bin/apple-ads-mcp; no macOS Intel, normalmente é /usr/local/bin/apple-ads-mcp.

Pacote de plugin e skill

Os arquivos de lançamento incluem .codex-plugin/plugin.json, .mcp.json e a skill apple-ads-operator. Esses arquivos descrevem o servidor e o fluxo de trabalho operacional seguro para carregadores de plugin compatíveis, mas não instalam o executável, registram o servidor MCP nem concedem acesso ao Apple Ads por si só. Este repositório não é distribuído atualmente por meio de um marketplace público de plugins do Codex; Homebrew mais registro do cliente é o caminho público de configuração suportado.

Verificar a conexão

Após reiniciar o cliente, confirme que apple-ads está habilitado ou conectado e peça para chamar server_info. Depois que as credenciais locais estiverem prontas, use o perfil e a conta explícitos para auth_check, ad_accounts_list e account_health.

Toda a verificação de configuração deve permanecer somente leitura. Não adicione --allow-writes, --allow-deletes, allowWrites ou allowDeletes ao solucionar problemas de instalação ou autenticação.

Solução de problemas

• Executável não encontrado: use "$(brew --prefix)/bin/apple-ads-mcp" na configuração do cliente em vez de um comando simples.
• Servidor já existe: remova apenas a entrada apple-ads existente desse cliente e adicione-a novamente com o caminho absoluto.
• Claude mostra aprovação pendente: aprove o servidor MCP do projeto, reconecte-se de /mcp e inicie uma nova conversa.
• Um cliente em execução ainda não tem ferramentas: reinicie completamente o aplicativo de desktop, a sessão CLI ou a extensão do IDE após alterar a configuração MCP.
• A autenticação falha: execute apple-ads-mcp auth doctor --profile <profile> localmente e confirme as permissões de arquivo e os identificadores não secretos; nunca cole a chave privada no chat.
• O Homebrew rejeita uma fórmula local baixada: instale a partir do tap confiável com brew install zelentsov-dev/tap/apple-ads-mcp.

Configuração liderada por agente

Um agente pode diagnosticar e executar a instalação somente com a aprovação do usuário. Ele deve verificar o binário, usar um caminho absoluto, registrar o escopo do cliente pretendido, reiniciar o cliente e parar após verificações de integridade somente leitura. Nunca deve solicitar o conteúdo da chave privada nem habilitar silenciosamente portões de mutação.

Habilitar gravações para uma sessão

Mantenha os perfis persistentes somente leitura. Para uma sessão de operador explicitamente autorizada, habilite ambos os portões locais:

APPLE_ADS_PROFILE=production-read-only \
APPLE_ADS_ALLOW_WRITES=true \
apple-ads-mcp serve --stdio --allow-writes

Isso não altera nada por si só. Toda mutação ainda precisa de profile explícito, adAccountId, uma prévia especializada, aplicação do recibo e verificação.

Configurar otimização sob demanda

Crie uma política local nomeada:

apple-ads-mcp optimization policy init
apple-ads-mcp optimization policy validate --name mature-product-balanced
apple-ads-mcp optimization doctor --policy mature-product-balanced

As políticas são armazenadas em ~/.config/apple-ads-mcp/optimization-policies.json com modo 0600. Cada política vincula um perfil, uma conta de anúncios, um aplicativo promovido e no máximo 20 IDs de campanha. O modo learning não exige meta de negócios e apenas retorna evidências. O modo active exige targetInstallCPA, limites de orçamento diário total e por campanha, e permissões explícitas para orçamento, lance, estratégia, pausa, retomada e novo teste. Uma política que permite alterações de lance também deve definir um maxBid positivo na moeda da conta; o limite de orçamento diário nunca é reutilizado como limite de lance.

O preset balanced exige exatamente 28 dias UTC consecutivos únicos concluídos terminando ontem, compara os últimos 7 dias com os 7 anteriores, aplica um período de espera de 72 horas, normalmente propõe alterações de 10% e nunca excede 20% por execução. Evidências de relatório ausentes, duplicadas, futuras, malformadas ou estouradas falham de forma fechada. Pode propor MAX_CONVERSIONS apenas para inventário elegível de Search Results Search Match com média de pelo menos cinco instalações por toque por dia ao longo de 14 dias. Nunca propõe exclusão.

Fluxo típico do agente:

1. Chame optimization_baseline e optimization_plan em um servidor somente leitura.
2. Revise as recomendações da Apple separadamente das ações calculadas.
3. Inicie uma sessão de gravação autorizada e chame optimization_plan_preview.
4. Inspecione OperationImpact, aplique o mesmo recibo uma vez e chame operations_verify.
5. Revise o histórico local limitado em ~/.local/share/apple-ads-mcp/optimization/.

Imediatamente antes da primeira gravação da Apple, o servidor persiste de forma durável uma intenção applying vinculada ao hash do recibo e uma receita de verificação tipada sanitizada sob um bloqueio de arquivo entre processos. Commits POSIX sincronizam o diretório contido; o Windows usa semântica de substituição com gravação direta. Um resultado desconhecido, verificação inconclusiva ou atualização de histórico interrompida bloqueia planos de otimização posteriores até que operations_verify reconcilie conclusivamente todos os itens afetados. A recuperação sobrevive ao reinício do processo e à expiração normal do recibo em memória, mas exige o recibo opaco original do operador. Uma ação matched ou matched_after reconciliada inicia o período de espera a partir do tempo original de intenção/aplicação; matched_before não. Uma campanha pode ser retomada automaticamente somente quando uma pausa verificada de propriedade do otimizador ainda tiver o mesmo modificationTime da Apple; qualquer alteração manual posterior revoga essa permissão. Nenhum recibo, credencial, envelope bruto da Apple ou contato de cobrança é armazenado no histórico de otimização.

Orçamentos compartilhados e operações de ciclo de vida

Mutações de orçamento compartilhado estão disponíveis somente quando a Apple relata o modelo de pagamento da conta como LOC. As operações de criação e atualização vinculam o orçamento exclusivamente à conta de anúncios explicitamente selecionada. As ferramentas de atribuição de campanha preservam atribuições existentes não relacionadas, e orçamentos compartilhados entre contas falham de forma fechada. Inicialize dados privados de cobrança localmente:

apple-ads-mcp billing profile init

~/.config/apple-ads-mcp/billing-profiles.json deve ser 0600. As entradas MCP contêm apenas o nome local billingProfile. Nomes de compradores e endereços de e-mail não são retornados na saída da ferramenta, logs, histórico ou prévias de recibo. Contas PAYG retornam not_eligible sem tentar uma gravação.

Para uma sessão de manutenção destrutiva explicitamente autorizada:

APPLE_ADS_ALLOW_WRITES=true \
APPLE_ADS_ALLOW_DELETES=true \
apple-ads-mcp serve --stdio --allow-writes --allow-deletes

O perfil baseado em arquivo selecionado já deve conter allowDeletes: true; allowWrites pode ser habilitado apenas para o processo atual com APPLE_ADS_ALLOW_WRITES=true. Os portões de exclusão do servidor e da sessão permanecem independentes. Use um *_delete_preview especializado, compare o impacto completo em cascata e o texto esperado exato, aplique uma vez e verifique deleted: true. Não use operações de ciclo de vida como parte de um plano de otimização.

Limites operacionais

• A Apple não fornece sandbox público da API de Ads. A aceitação de mutação ao vivo é manual, explicitamente habilitada, usa fixtures PAUSED claramente nomeados e nunca faz parte de CI automático.
• Elegibilidade, sugestões, popularidade, recomendações, relatórios e suporte criativo variam por conta e storefront.
• Contas frias podem não ter recomendações de CPA-alvo ou orçamento diário.
• Nomes de campanhas e objetos são validados pela Apple; a interface web e a API podem aceitar pontuação diferente.
• A Apple rejeita o caractere de barra vertical (|) em nomes de campanhas; use um nome legível com hífen. A criação de grupo de anúncios exige um startTime ISO 8601 no fuso horário da conta de anúncios.
• Relatórios podem atrasar e permanecer vazios até que a entrega ocorra.
• A Apple rejeita a exclusão individual de um anúncio que usa a Default Product Page (CAN_NOT_DELETE_DPP_CREATIVE_AD). O servidor retorna not_eligible durante a prévia; use exclusão de ciclo de vida apenas para anúncios e criativos descartáveis de Custom Product Page.
• A atribuição de teste e assinatura pertence à sua pilha de atribuição; a API da Apple Ads Platform sozinha não prova atribuição de palavra-chave a teste.

Respostas conhecidas da API da Apple

Em 2026-08-25, as formas de solicitação v1 documentadas usadas por este servidor produziram dois comportamentos upstream repetíveis durante a aceitação ao vivo:

• phrase_suggestions e category_suggestions podem retornar Apple HTTP 500 para uma consulta SUGGESTION mesmo quando keyword_suggestions e target_cpa_suggestions funcionam para o mesmo aplicativo de propriedade.
• impression_share pode retornar Apple HTTP 400 em uma conta fria ou totalmente pausada. Uma conta de aceitação controlada pelo proprietário não forneceu código ou detalhes de diagnóstico; reproduções públicas também relataram código INVALID_VALUE. Entrega recente ausente pode ser relevante, mas não é um pré-requisito ou solução alternativa confirmado pela Apple.

O servidor retorna esses como erros estruturados limitados da Apple e não os converte em resultados vazios ou bem-sucedidos. Campos seguros de código, mensagem e detalhe da Apple são retidos para 4xx; corpos de solicitação, credenciais, campos arbitrários e corpos 5xx não são retornados. As formas de solicitação correspondem à API atual da Apple Ads Platform e ao cliente Java oficial da Apple. Reproduções públicas comparáveis de v1 estão registradas em App Store Connect CLI PR #2057 e PR #2020. Reverifique após a Apple alterar a API ou a conta ter histórico significativo de entrega.

Compatibilidade

v0.3 preserva todos os nomes e esquemas de ferramentas v0.2.1 e adiciona ferramentas de otimização, mutação de orçamento compartilhado, estratégia de lance e ciclo de vida. v0.3.1 adiciona um maxBid obrigatório quando a permissão de lance está habilitada e regras de reconciliação com falha fechada; consulte as notas de migração v0.3.1. v0.3.2 altera apenas distribuição e onboarding. v0.3.3 muda a verificação de lançamento para o caminho exato da fórmula do tap, v0.3.4 adiciona confiança com escopo de fórmula para Homebrew 6 e v0.3.5 desambigua a detecção de versão do Homebrew colocando a versão semântica no final dos nomes de arquivo. v0.3.6 mantém nomes de ferramentas existentes e entradas legadas compatíveis, adicionando aliases tipados, atalhos de consulta, diagnósticos e escopos obrigatórios mais rígidos; consulte as notas v0.3.6. Clientes mais antigos também devem ler as notas v0.3 e notas v0.2.

O esquema público de ferramentas não está congelado antes da v1.0. O escopo da família de API e o status da operação são rastreados na matriz de operações legível por máquina. A linha de base oficial do cliente Java e o inventário de endpoints da App Store são rastreados em upstream-baseline.json.

Desenvolvimento

gofmt -w cmd internal
go test ./...
go test -race ./...
go vet ./...
go run honnef.co/go/tools/cmd/staticcheck@v0.8.1 -checks 'all,-ST1000,-ST1005' ./...
go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
go run github.com/zricethezav/gitleaks/v8@v8.29.1 dir --no-banner --redact .
go run github.com/goreleaser/goreleaser/v2@v2.17.1 check
go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.12
npx --yes markdownlint-cli2@0.23.2 '**/*.md'
python3 scripts/validate_distribution.py
python3 scripts/audit_upstream.py

Consulte CONTRIBUTING.md, SECURITY.md e o roadmap.

Licença

MIT