Apple Ads MCP

Servidor MCP local-first para investigación, optimización y gestión de campañas de App Store con control de recibos en Apple Ads, desde Claude, Codex y otros clientes MCP.

GitHub
6

Documentación

Apple Ads MCP

CI Release Go License

Apple Ads MCP es un servidor Model Context Protocol local-first para la Apple Ads Platform API v1. Proporciona a Codex, Claude y otros clientes MCP herramientas tipadas para investigar, inspeccionar y operar de forma segura cuentas de publicidad en App Store.

El servidor es de solo lectura por defecto. Las credenciales permanecen en tu máquina, cada llamada con ámbito de cuenta nombra un perfil explícito y una cuenta publicitaria, y cada mutación requiere una vista previa más un recibo de un solo uso de corta duración.

Apple Ads MCP es software de código abierto independiente. No está afiliado, respaldado ni patrocinado por Apple Inc. Apple Ads y App Store son marcas comerciales de Apple Inc.

Inicio rápido

Instala el binario publicado con Homebrew en macOS o Linux:

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

Crea un perfil local de solo lectura. El comando almacena una ruta absoluta de clave privada; nunca pegues la clave privada en un chat, issue, registro o repositorio:

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

Registra el servidor con una ruta absoluta de Homebrew para que las aplicaciones de escritorio y las extensiones de IDE no dependan de su PATH de shell heredado.

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

Reinicia una aplicación de escritorio, sesión CLI o extensión de IDE ya en ejecución, luego inicia una nueva conversación. Una primera solicitud segura es:

Llama a server_info, luego ejecuta account_health para mi perfil explícito, cuenta publicitaria y aplicación. No habilites escrituras.

Otros iniciadores de solo lectura útiles:

  • "Enumera las aplicaciones que puedo anunciar y explica cualquier brecha de elegibilidad."
  • "Audita mi estructura actual de campañas de Apple Ads sin cambiar nada."
  • "Encuentra oportunidades de palabras clave y separa la evidencia de Apple de tus inferencias."

Versión actual

v0.3.6 es la versión actual. Agrega diagnósticos accionables tipados, corrige la creación masiva de palabras clave de Apple con IDs de correlación enteros basados en cero y un recibo agregado entre grupos, y ajusta los contratos de lectura/consulta sin eliminar las entradas heredadas id, filters o masivas de nivel superior adGroupId. Consulta las notas de la versión v0.3.6 y migración.

El nombre de archivo de archivo final de la versión v0.3.5, la confianza con ámbito de fórmula de v0.3.4, la verificación de ruta exacta de v0.3.3 y la incorporación con un solo comando de v0.3.2 permanecen intactos.

La optimización nunca es autónoma: el servidor no tiene programador y nunca cambia el gasto en segundo plano. Una sesión de solo lectura puede construir una línea base y un plan. Aplicar un plan aún requiere cada puerta de escritura, una política nombrada activa, un recibo, un informe fresco y una verificación de deriva de inventario, y verificación a nivel de elemento.

La versión admite las cuatro ubicaciones de App Store expuestas por Apple:

  • Resultados de búsqueda
  • Pestaña de búsqueda
  • Pestaña Hoy
  • Páginas de producto

La disponibilidad de ubicación aún depende de la cuenta seleccionada, la aplicación, la tienda, el creativo y la respuesta de elegibilidad de Apple. Una ubicación no disponible se reporta como not_eligible; el servidor no intenta omitir la validación de Apple.

Las palabras clave y las palabras clave negativas son recursos de Resultados de búsqueda. La Platform API rechaza recursos explícitos Ad para campañas de Resultados de búsqueda, por lo que esa ubicación se opera a través de su campaña, grupo de anuncios, palabras clave y configuración de página de producto; los anuncios explícitos permanecen sujetos a elegibilidad para las otras ubicaciones. Un creativo de Página de producto predeterminada es único por aplicación y cuenta publicitaria, por lo que los operadores deben consultarlo y reutilizarlo en lugar de intentar crear un duplicado.

Qué puede hacer

ÁreaHerramientas principales
Acceso y preparaciónauth_check, ad_accounts_list, ad_account_get, advertiser_resources_list, account_health
Aplicaciones y tiendasapps_search, apps_get, apps_eligibility, app_locale_details, supported_app_languages, app_store_geo_search
Inventariocampaigns_query, ad_groups_query, keywords_query, negative_keywords_query, ads_query, creatives_query, shared_budgets_query, campaign_inventory
Diagnósticosrazones de rechazo, razones de estado de campaña, historial de cambios, auditorías de cuenta y campaña
Investigaciónsugerencias de palabras clave, frases, categorías, CPA objetivo, popularidad de búsqueda, participación de impresiones
Informesinformes tipados de campaña, grupo de anuncios, anuncio, palabra clave y término de búsqueda
Operación de campañasvistas previas de crear/actualizar, presupuesto, países, programación, pausa y reanudación
Operación de grupos de anunciosvistas previas de crear/actualizar, programación, segmentación, Search Match, oferta, límite de CPA, pausa y reanudación
Palabras clavevistas previas de crear/actualizar individuales y masivas de palabras clave de segmentación/negativas, oferta, pausa y reanudación
Anuncios y creativosvistas previas de crear/actualizar, pausa y reanudación de creativos tipados de App Store y anuncios
Recomendacioneslectura, vista previa de aplicación y vista previa de descarte para presupuesto diario y CPA objetivo
Optimizaciónpolíticas locales nombradas, líneas base de 28 días, planes de aprendizaje/activos, vista previa/aplicación/verificación compuestos e historial acotado
Presupuestos compartidosvistas previas tipadas solo LOC de crear/actualizar/asignar/desasignar con perfiles de facturación locales privados
Ciclo de vidavistas previas de eliminación por separado con puertas para campaña, grupo de anuncios, palabra clave, palabra clave negativa, anuncio, creativo y presupuesto compartido
Verificaciónoperations_inspect, operations_apply, operations_verify y lectura directa de recursos

Cada lista está limitada a 200 elementos y usa paginación next. Las respuestas incluyen texto conciso más structuredContent de MCP; los sobres crudos de Apple y la PII de contacto de facturación no se exponen.

No hay herramienta de solicitud cruda, mutación de cuenta/delegación, programador automático, superficie de Apple Maps ni soporte heredado de Campaign Management API v5.

Modelo de seguridad

Una escritura es posible solo cuando todas las puertas pasan:

  1. El usuario de la API de Apple tiene un rol de escritura compatible.
  2. El servidor se inicia con --allow-writes.
  3. El perfil seleccionado tiene allowWrites: true.
  4. Una herramienta especializada *_preview valida la cuenta, la aplicación, la tienda, la ubicación, la moneda y la carga útil.
  5. operations_apply recibe el mismo recibo no vencido.
  6. El inventario afectado aún coincide con el estado capturado durante la vista previa.

Los recibos de vista previa expiran después de diez minutos y son de un solo uso para aplicar. Una tumba acotada preserva el estado expirado explícito después de que se poda el registro completo del recibo. Cada recibo de mutación vincula ámbitos de objetos canónicos para sus IDs objetivo y retiene huellas de lectura exactas; las creaciones y eliminaciones de padres también vinculan el inventario afectado y los ámbitos de cascada acotados. Las formas de verificación genéricas, masivas, de eliminación, de recomendación, de presupuesto compartido y de optimización para objetos superpuestos no pueden despacharse de forma concurrente. Los inventarios de grupos de anuncios independientes permanecen en paralelo. Los recibos masivos devuelven estados a nivel de elemento applied, failed o unknown. Un recibo masivo de palabras clave de segmentación puede contener múltiples grupos de anuncios por elemento mientras envía una sola solicitud masiva de Apple. Apple puede aceptar parcialmente un lote; el servidor nunca promete reversión. Si una aplicación de optimización tiene un resultado no resuelto, una receta de recuperación saneada permanece en el historial local solo del propietario para que operations_verify pueda conciliar el recibo proporcionado después de un reinicio del proceso o una expulsión normal de vista previa.

Las vistas previas independientes de la misma instantánea de inventario se desvían intencionalmente después de la primera aplicación. Coloca las creaciones de palabras clave relacionadas en una vista previa masiva cuando deban aplicarse como una unidad; el servidor no debilita este invariante de cierre ante fallos.

Las solicitudes de mutación no se reintentan después de un tiempo de espera. El resultado es committed_unverified, o a nivel de elemento unknown, hasta que operations_verify y la lectura directa establezcan el estado real.

Las operaciones de aplicación de recomendaciones requieren un maximumAmount explícito. La moneda de la recomendación debe coincidir con la cuenta publicitaria, el monto propuesto debe permanecer bajo el límite, y la recomendación más la campaña promovida se releen antes de aplicar.

Una eliminación irreversible tiene cinco puertas adicionales: --allow-deletes, perfil allowDeletes: true, APPLE_ADS_ALLOW_DELETES=true solo de sesión, un nombre de objeto o texto de palabra clave esperado exacto, y un recibo de eliminación especializado. Las campañas y los padres deben estar PAUSED; el inventario en cascada está acotado y con hash; los creativos no deben tener anuncios referenciados; los presupuestos compartidos no deben tener asignaciones. DELETE nunca se reintenta después de un resultado ambiguo.

Validación de la versión

La versión v0.3.6 requiere la suite de compatibilidad completa, pruebas de contrato stdio de MCP, pruebas unitarias y HTTP, el detector de carreras, análisis estático, escaneos de vulnerabilidades y secretos, y validación de distribución. CI multiplataforma se ejecuta en macOS, Linux y Windows.

La confirmación en tiempo de ejecución es una puerta separada controlada por el propietario. El 2026-08-31, la matriz de solo lectura P2 de v0.3.6 y un fixture masivo de palabras clave de segmentación PAUSED autorizado por separado con 2 y 28 elementos pasaron contra Apple Ads API v1. Ambos recibos agregados aplicaron y verificaron cada ID de palabra clave devuelto directamente; la campaña y el grupo de anuncios permanecieron PAUSED durante toda la aceptación de escritura.

La aceptación en vivo anterior de v0.3.x confirmó líneas base y planes de optimización de solo lectura, creación y lectura de fixtures PAUSED, actualizaciones de presupuesto/oferta/estrategia, pausa/reanudación, verificaciones de deriva de recibos, verificación de elementos y eliminación de campañas, grupos de anuncios, palabras clave y palabras clave negativas desechables. Todos los fixtures retenidos permanecieron PAUSED con cero gasto. Esta evidencia histórica no reemplaza la nueva puerta de aceptación masiva/P2 de v0.3.6.

Las rutas dependientes de cuenta tienen un límite de evidencia explícito:

  • La aplicación de planes de optimización activos y MAX_CONVERSIONS permanecen verificados por pruebas automatizadas hasta que una campaña madura seleccionada deliberadamente cumpla con el mínimo de 14 días de datos y las puertas de elegibilidad de Apple.
  • La creación/actualización/asignación/eliminación de presupuestos compartidos permanecen verificadas por contrato y pruebas HTTP porque la cuenta de aceptación en vivo usa PAYG; Apple requiere LOC.
  • La eliminación de anuncios y creativos de Página de producto predeterminada se confirma como not_eligible porque Apple no permite eliminar esos recursos individualmente.

Estos límites no debilitan el modelo de seguridad predeterminado: las operaciones no compatibles o insuficientemente evidenciadas fallan cerradas y nunca se convierten en respuestas vacías exitosas.

Instalación

PlataformaHomebrewArchivo de GitHubImagen OCI
macOS arm64 / amd64Sí.tar.gzSolo contenedor Linux
Linux arm64 / amd64Sí.tar.gzSí
Windows arm64 / amd64No.zipSolo contenedor Linux

Homebrew

El tap oficial instala un binario de versión fijado por suma de verificación:

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

Actualiza versiones posteriores con:

brew update
brew upgrade apple-ads-mcp

Versión de GitHub

Descarga el archivo para tu plataforma desde GitHub Releases. Las versiones incluyen sumas de verificación SHA-256 y SBOM SPDX.

Ejemplo 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

Los usuarios de Windows deben verificar checksums.txt, extraer el ZIP correspondiente y registrar el ejecutable con su ruta absoluta.

Imagen OCI

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

La imagen ejecuta serve --stdio por defecto. Monta accounts.json y su clave privada referenciada en modo solo lectura.

Compilar desde el código fuente

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

Se requiere Go 1.26.7 o más reciente.

Configuración de la API de Apple

El acceso a la API de Apple Ads es separado del acceso a App Store Connect. Un Administrador de cuenta de Apple Ads debe agregar un usuario de API con el rol apropiado. Prefiere API Account Read Only hasta que se necesiten cambios de campaña.

Genera un par de claves 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

Sube solo la clave pública en Apple Ads. Nunca pegues la clave privada en una conversación de agente, issue, registro o repositorio. Después de que Apple registre la clave, registra el ID de cliente, ID de equipo e ID de clave mostrados en la interfaz de Apple Ads.

Configurar

Crea un perfil interactivamente:

apple-ads-mcp config init

La ruta de configuración predeterminada es ~/.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
    }
  ]
}

En sistemas POSIX, la configuración y la clave privada deben ser solo del propietario:

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

Valida la autenticación y descubre cuentas publicitarias accesibles:

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

La precedencia de configuración es --config, APPLE_ADS_MCP_CONFIG, el archivo predeterminado y luego las variables de entorno de perfil único APPLE_ADS_*. Las variables de perfil único compatibles son 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 y APPLE_ADS_ALLOW_DELETES. Para un perfil respaldado por archivo, las variables de entorno no otorgan silenciosamente permiso persistente de escritura o eliminación.

Conectar un cliente MCP

El servidor usa stdio y escribe MCP JSON-RPC solo en stdout:

apple-ads-mcp serve --stdio

Para clientes con CLI, prefiera una ruta binaria absoluta.

Configuración global de Codex:

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

Codex Desktop, la CLI de Codex y la extensión del IDE comparten la misma configuración del host. Reinicie un cliente ya en ejecución y abra una nueva conversación después de agregar el servidor.

Configuración de usuario de Claude Code:

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

La configuración del proyecto de Claude puede usar el .mcp.json del repositorio, pero cada espacio de trabajo/servidor puede permanecer pendiente hasta que el usuario lo apruebe. Reconéctese desde /mcp o reinicie Claude Code después de la aprobación.

Configuración genérica de MCP para clientes sin comando de registro:

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

Reemplace apple-ads-mcp con la ruta ejecutable absoluta cuando el cliente no herede el PATH de Homebrew o del shell. En Apple silicon, la ruta predeterminada de Homebrew es /opt/homebrew/bin/apple-ads-mcp; en macOS Intel normalmente es /usr/local/bin/apple-ads-mcp.

Paquete de complementos y habilidades

Los archivos de lanzamiento incluyen .codex-plugin/plugin.json, .mcp.json y la habilidad apple-ads-operator. Estos archivos describen el servidor y el flujo de trabajo operativo seguro para cargadores de complementos compatibles, pero no instalan el ejecutable, registran el servidor MCP ni otorgan acceso a Apple Ads por sí mismos. Este repositorio no se distribuye actualmente a través de un mercado público de complementos de Codex; Homebrew más el registro del cliente es la ruta de configuración pública compatible.

Verificar la conexión

Después de reiniciar el cliente, confirme que apple-ads esté habilitado o conectado y pídale que llame a server_info. Cuando las credenciales locales estén listas, use el perfil y la cuenta explícitos para auth_check, ad_accounts_list y account_health.

Toda la verificación de configuración debe permanecer de solo lectura. No agregue --allow-writes, --allow-deletes, allowWrites o allowDeletes mientras soluciona problemas de instalación o autenticación.

Solución de problemas

  • Ejecutable no encontrado: use "$(brew --prefix)/bin/apple-ads-mcp" en la configuración del cliente en lugar de un comando simple.
  • El servidor ya existe: elimine solo la entrada apple-ads existente de ese cliente y luego agréguela nuevamente con la ruta absoluta.
  • Claude muestra aprobación pendiente: apruebe el servidor MCP del proyecto, reconéctese desde /mcp e inicie una nueva conversación.
  • Un cliente en ejecución aún carece de herramientas: reinicie por completo la aplicación de escritorio, la sesión CLI o la extensión del IDE después de cambiar la configuración de MCP.
  • La autenticación falla: ejecute apple-ads-mcp auth doctor --profile <profile> localmente y confirme los permisos de archivo y los identificadores no secretos; nunca pegue la clave privada en el chat.
  • Homebrew rechaza una fórmula local descargada: instale desde el tap confiable con brew install zelentsov-dev/tap/apple-ads-mcp.

Configuración dirigida por agente

Un agente puede diagnosticar y realizar la instalación solo con la aprobación del usuario. Debe verificar el binario, usar una ruta absoluta, registrar el alcance del cliente previsto, reiniciar el cliente y detenerse después de verificaciones de salud de solo lectura. Nunca debe solicitar el contenido de la clave privada ni habilitar silenciosamente las puertas de mutación.

Habilitar escrituras para una sesión

Mantenga los perfiles persistentes de solo lectura. Para una sesión de operador explícitamente autorizada, habilite ambas puertas locales:

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

Esto no cambia nada por sí mismo. Cada mutación aún necesita profile explícito, adAccountId, una vista previa especializada, aplicación de recibo y verificación.

Configurar optimización bajo demanda

Cree una política local con nombre:

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

Las políticas se almacenan en ~/.config/apple-ads-mcp/optimization-policies.json con modo 0600. Cada política vincula un perfil, una cuenta publicitaria, una aplicación promocionada y como máximo 20 ID de campaña. El modo learning no requiere objetivo comercial y solo devuelve evidencia. El modo active requiere targetInstallCPA, límites de presupuesto diario total y por campaña, y permisos explícitos para presupuesto, oferta, estrategia, pausa, reanudación y nueva prueba. Una política que permite cambios de oferta también debe establecer un maxBid positivo en la moneda de la cuenta; el límite de presupuesto diario nunca se reutiliza como límite de oferta.

El ajuste preestablecido balanced requiere exactamente 28 días UTC consecutivos únicos completados que terminen ayer, compara los últimos 7 días con los 7 anteriores, aplica un período de enfriamiento de 72 horas, normalmente propone cambios del 10% y nunca supera el 20% por ejecución. La evidencia de informe faltante, duplicada, futura, malformada o desbordada falla de forma cerrada. Puede proponer MAX_CONVERSIONS solo para inventario elegible de Search Results Search Match que promedie al menos cinco instalaciones de tap por día durante 14 días. Nunca propone eliminación.

Flujo típico del agente:

  1. Llame a optimization_baseline y optimization_plan en un servidor de solo lectura.
  2. Revise las recomendaciones de Apple por separado de las acciones calculadas.
  3. Inicie una sesión de escritura autorizada y llame a optimization_plan_preview.
  4. Inspeccione OperationImpact, aplique el mismo recibo una vez y luego llame a operations_verify.
  5. Revise el historial local limitado bajo ~/.local/share/apple-ads-mcp/optimization/.

Inmediatamente antes de la primera escritura de Apple, el servidor persiste de forma duradera una intención applying vinculada al hash del recibo y una receta de verificación tipificada saneada bajo un bloqueo de archivo entre procesos. Las confirmaciones POSIX sincronizan el directorio contenedor; Windows usa semántica de reemplazo con escritura directa. Un resultado desconocido, una verificación no concluyente o una actualización de historial interrumpida bloquean los planes de optimización posteriores hasta que operations_verify concilie de manera concluyente todos los elementos afectados. La recuperación sobrevive al reinicio del proceso y a la expiración normal del recibo en memoria, pero requiere el recibo opaco original del operador. Una acción matched o matched_after conciliada inicia el enfriamiento desde su tiempo original de intención/aplicación; matched_before no. Una campaña solo se puede reanudar automáticamente cuando una pausa verificada propiedad del optimizador aún tiene el mismo modificationTime de Apple; cualquier cambio manual posterior revoca ese permiso. No se almacena ningún recibo, credencial, sobre sin procesar de Apple o contacto de facturación en el historial de optimización.

Presupuestos compartidos y operaciones de ciclo de vida

Las mutaciones de presupuesto compartido están disponibles solo cuando Apple informa el modelo de pago de la cuenta como LOC. Las operaciones de creación y actualización vinculan el presupuesto exclusivamente a la cuenta publicitaria seleccionada explícitamente. Las herramientas de asignación de campañas preservan las asignaciones existentes no relacionadas, y los presupuestos compartidos entre cuentas fallan de forma cerrada. Inicialice los datos de facturación privados localmente:

apple-ads-mcp billing profile init

~/.config/apple-ads-mcp/billing-profiles.json debe ser 0600. Las entradas de MCP contienen solo el nombre local billingProfile. Los nombres de compradores y direcciones de correo electrónico no se devuelven en la salida de herramientas, registros, historial o vistas previas de recibos. Las cuentas PAYG devuelven not_eligible sin intentar una escritura.

Para una sesión de mantenimiento destructivo explícitamente autorizada:

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

El perfil respaldado por archivo seleccionado ya debe contener allowDeletes: true; allowWrites puede habilitarse solo para el proceso actual con APPLE_ADS_ALLOW_WRITES=true. Las puertas de eliminación del servidor y de la sesión permanecen independientes. Use un *_delete_preview especializado, compare el impacto completo en cascada y el texto esperado exacto, aplique una vez y verifique deleted: true. No use operaciones de ciclo de vida como parte de un plan de optimización.

Límites operativos

  • Apple no proporciona un sandbox público de la API de Ads. La aceptación de mutaciones en vivo es manual, explícitamente habilitada, usa accesorios PAUSED claramente nombrados y nunca es parte de CI automático.
  • La elegibilidad, sugerencias, popularidad, recomendaciones, informes y soporte creativo varían según la cuenta y la tienda.
  • Las cuentas frías pueden no tener recomendaciones de CPA objetivo o presupuesto diario.
  • Los nombres de campañas y objetos son validados por Apple; la interfaz web y la API pueden aceptar puntuación diferente.
  • Apple rechaza el carácter de barra vertical (|) en los nombres de campañas; use un nombre legible con guiones en su lugar. La creación de grupos de anuncios requiere un startTime ISO 8601 en la zona horaria de la cuenta publicitaria.
  • Los informes pueden retrasarse y permanecer vacíos hasta que ocurra la entrega.
  • Apple rechaza la eliminación individual de un anuncio que usa la Página de Producto Predeterminada (CAN_NOT_DELETE_DPP_CREATIVE_AD). El servidor devuelve not_eligible durante la vista previa; use la eliminación de ciclo de vida solo para anuncios y creatividades de Página de Producto Personalizada desechables.
  • La atribución de pruebas y suscripciones pertenece a su pila de atribución; la API de la Plataforma de Apple Ads por sí sola no prueba la atribución de palabra clave a prueba.

Respuestas conocidas de la API de Apple

A partir del 2026-08-25, las formas de solicitud v1 documentadas utilizadas por este servidor han producido dos comportamientos ascendentes repetibles durante la aceptación en vivo:

  • phrase_suggestions y category_suggestions pueden devolver el HTTP 500 de Apple para una consulta SUGGESTION incluso cuando keyword_suggestions y target_cpa_suggestions funcionan para la misma aplicación propiedad.
  • impression_share puede devolver el HTTP 400 de Apple en una cuenta fría o completamente pausada. Una cuenta de aceptación controlada por el propietario no proporcionó código ni detalles de diagnóstico; las reproducciones públicas también han informado el código INVALID_VALUE. La falta de entrega reciente puede ser relevante, pero no es un requisito previo o solución confirmada de Apple.

El servidor devuelve estos como errores estructurados limitados de Apple y no los convierte en resultados vacíos o exitosos. Los campos seguros de código, mensaje y detalle de Apple se conservan para 4xx; los cuerpos de solicitud, credenciales, campos arbitrarios y cuerpos 5xx no se devuelven. Las formas de solicitud coinciden con la API actual de la Plataforma de Apple Ads y el cliente Java oficial de Apple. Las reproducciones públicas comparables de v1 están registradas en App Store Connect CLI PR #2057 y PR #2020. Vuelva a verificar después de que Apple cambie la API o la cuenta tenga un historial de entrega significativo.

Compatibilidad

v0.3 preserva todos los nombres y esquemas de herramientas de v0.2.1, y luego agrega herramientas de optimización, mutación de presupuesto compartido, estrategia de oferta y ciclo de vida. v0.3.1 agrega un maxBid requerido cuando el permiso de oferta está habilitado y reglas de conciliación de fallo cerrado; consulte las notas de migración de v0.3.1. v0.3.2 cambia solo la distribución y la incorporación. v0.3.3 cambia la verificación de lanzamiento a la ruta exacta de la fórmula del tap, v0.3.4 agrega confianza con ámbito de fórmula para Homebrew 6 y v0.3.5 desambigua la detección de versión de Homebrew colocando la versión semántica al final de los nombres de archivo. v0.3.6 mantiene los nombres de herramientas existentes y las entradas heredadas compatibles mientras agrega alias tipificados, accesos directos de consulta, diagnósticos y ámbitos requeridos más estrictos; consulte las notas de v0.3.6. Los clientes más antiguos también deben leer las notas de v0.3 y las notas de v0.2.

El esquema público de herramientas no está congelado antes de v1.0. El alcance de la familia de API y el estado de la operación se rastrean en la matriz de operaciones legible por máquina. La línea base oficial del cliente Java y el inventario de endpoints de App Store se rastrean en upstream-baseline.json.

Desarrollo

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 y la hoja de ruta.

Licencia

MIT