Collegare Apple Search Ads a Claude o ChatGPT in cinque minuti

Il connettore Hermoso per Apple Search Ads collega il tuo account Apple Ads a Claude, ChatGPT, Cursor, la CLI o HTTP semplice, così un agente può gestire per te le campagne di ricerca sull'App Store. Crea la campagna, il gruppo di annunci, le parole chiave di targeting e quelle negative, rilegge ciò che Apple ha effettivamente salvato e riporta le prestazioni fino al singolo termine di ricerca che qualcuno ha digitato prima di installare. Tutto ciò che viene creato parte in pausa, e attivare la spesa è un passaggio a parte, che richiede una conferma esplicita. I report possono finire in un Google Sheet, in una dashboard Looker Studio o in un file JSON, e la pagina MCP di Apple Ads elenca tutto ciò che il connettore sa fare.

Collegarlo richiede circa cinque minuti. Non dovrai eseguire openssl, e nessuna password Apple finisce in Hermoso.

Collegare Apple Search Ads a Claude

Per collegare Apple Search Ads a Claude, aggiungi Hermoso a Claude come connettore, poi collega il tuo account Apple Ads dentro Hermoso una sola volta. In Claude apri Customize › Connectors › Add custom connector, dai il nome Hermoso, incolla https://app.hermoso.ai/mcp e approva con il tuo account Hermoso. Non c'è nessuna chiave da incollare in Claude. Poi collega Apple Ads in Hermoso da Impostazioni › Connettori, seguendo i passaggi più avanti in questa pagina. Da quel momento Claude può usare tutti gli strumenti Apple Ads di Hermoso: chiedi un report, una modifica alle parole chiave o una nuova campagna con parole semplici. In Claude Code bastano due comandi: /plugin marketplace add hermoso-ai/hermoso, poi /plugin install hermoso@hermoso. Hermoso in Claude riporta tutti i passaggi.

Collegare Apple Search Ads a ChatGPT

Con ChatGPT il procedimento è lo stesso. In ChatGPT apri Plugins, poi Add › Create MCP App, dai il nome Hermoso, incolla https://app.hermoso.ai/mcp come Server URL, lascia Authentication su OAuth e approva con il tuo account Hermoso. Se Create MCP App non compare, attiva una volta la modalità sviluppatore da Settings › Plugins › Developer mode. Con Apple Ads collegato in Hermoso, ChatGPT può estrarre il tuo report sulle parole chiave, scriverlo in un Google Sheet o preparare una campagna da controllare prima che parta. Hermoso in ChatGPT ti guida passo passo.

Cursor, Codex e qualsiasi altro client MCP

Ogni client che parla il Model Context Protocol raggiunge gli stessi strumenti allo stesso indirizzo. Cursor legge https://app.hermoso.ai/mcp dal suo mcp.json; Codex usa il plugin Hermoso con codex plugin marketplace add hermoso-ai/hermoso, che esegue gli stessi strumenti dal terminale. Qualunque client tu usi, le tue credenziali Apple non passano mai dalla chat. L'agente chiama gli strumenti di Hermoso, e Hermoso firma ogni richiesta ad Apple con la chiave che custodisce. La pagina MCP di Apple Ads elenca ogni strumento.

Cosa chiedere una volta collegato

• “Mostrami le prestazioni di Apple Search Ads della scorsa settimana per parola chiave e fammi vedere le dieci con il costo per acquisizione più alto.”
• “Metti la spesa, le installazioni e il CPA degli ultimi 30 giorni per campagna in un nuovo Google Sheet chiamato Apple Ads.” (Collega prima Google Drive.)
• “Quali termini di ricerca hanno portato installazioni nella mia campagna US questo mese, senza che li abbia ancora impostati come parole chiave esatte?”
• “Aggiungi ‘budget planner’ e ‘expense tracker’ come parole chiave a corrispondenza esatta nel gruppo di annunci Brand, e ‘jobs’ come negativa.”
• “Quali parole chiave suggerisce Apple per la mia app, e che quota di impression ottengo su quelle che già offro?”
• “Crea una campagna in pausa per la mia app nel Regno Unito con un budget giornaliero di 50 dollari, poi mostrami cosa ha salvato Apple.”

Leggere un report non tocca mai la spesa. Ciò che l'agente crea parte in pausa, e l'interruttore che attiva la spesa aspetta la tua conferma esplicita.

Prima di tutto, l'ostacolo che blocca quasi tutti

Le istruzioni di Apple dicono: “Dall'interfaccia Ads, scegli Account Settings › API. Incolla la chiave nel campo Public Key.”

Quel campo non esiste per un Account Admin. Accedi come amministratore sul tuo account, apri Account Settings › API, e compare una tabella intitolata Manage API Access (un elenco di fornitori di servizi terzi con una sola azione, Remove Access) e nessun campo per la chiave in tutta la pagina. Sembra una funzione mancante, ed è proprio per questo che molti si fermano qui e concludono che l'API non è disponibile per loro.

Invece lo è. Il campo Public Key appartiene a un utente che ha un ruolo API, e non basta essere amministratore dell'account. L'invito di Apple offre sei ruoli, di cui esattamente due sono ruoli API:

• API Account Manager: “accesso in lettura e scrittura a tutti i gruppi di campagne per la gestione tramite API”. È quello da scegliere se vuoi che Hermoso crei campagne, non solo che ne riporti i dati.
• API Account Read Only: “accesso in sola lettura a tutti i gruppi di campagne per la gestione tramite API”. Basta per i report, e nient'altro.

Gli altri quattro (Account Admin, Account Finance, Account Read Only e Limited Access) non possono creare affatto credenziali API. Quindi la soluzione è un invito che mandi a te stesso:

1. Apri Account Settings › User Management e scegli Invite Users.
2. Invita un indirizzo che controlli (il tuo, oppure uno condiviso come ads-api@yourcompany.com, così la credenziale sopravvive a una singola persona) con il ruolo API Account Manager.
3. Accetta l'invito dalla casella di quell'indirizzo, poi accedi ad Apple Ads come quell'utente.

Ora in Account Settings › API compare il campo Public Key.

La connessione, passo dopo passo

1. Avviala in Hermoso. Impostazioni › Connettori › Apple Ads › Connetti. Hermoso genera una chiave di firma EC P-256 (la stessa chiave prime256v1 che avrebbero prodotto i due comandi openssl di Apple) e ti mostra solo la metà pubblica. Copiala.
2. Dai la metà pubblica ad Apple. Come utente con il ruolo API, apri Account Settings › API, incollala nel campo Public Key e salva.
3. Copia i tre identificativi. Apple ora mostra clientId, teamId e keyId sopra quel campo. Tutti e tre.
4. Completa in Hermoso. Incolla i tre identificativi e salva. Hermoso scambia un token con Apple e legge l'elenco delle tue organizzazioni prima di salvare qualsiasi cosa, quindi un identificativo digitato male fallisce subito, mentre hai ancora sotto gli occhi ciò che hai incollato, e non alla prima lettura di un report, un'ora dopo.
5. Scegli l'organizzazione, se le tue credenziali ne coprono più di una. La connessione è vincolata a quella che scegli.

Se qualcosa va storto

Nella pagina API non c'è il campo Public Key

Sei connesso come Account Admin, oppure come uno dei quattro ruoli non API. Invitati come API Account Manager e accedi come quell'utente (vedi sopra). È il motivo più comune per cui una connessione Apple Ads non si completa mai.

Apple rifiuta le credenziali

I tre identificativi devono appartenere alla chiave che Apple sta conservando. Ricopia clientId, teamId e keyId da subito sopra il campo Public Key, non da una chiave precedente che hai sostituito. Se continuano a fallire, riavvia la connessione in Hermoso: genera una nuova coppia di chiavi e incolli la nuova metà pubblica in Apple.

La sessione di configurazione è scaduta

Hermoso conserva la chiave privata generata per 24 ore, mentre tu vai a incollare la sua metà pubblica in Apple. Passato questo termine viene eliminata, di proposito. Riavvia la connessione e incolla la nuova chiave pubblica.

Avevo già generato una chiave con openssl

Allora usala. Incolla la tua chiave privata EC P-256 esistente quando ti colleghi, invece di quella di Hermoso, e la chiave pubblica già presente nel tuo account Apple continua a funzionare. Deve essere una chiave EC P-256 (prime256v1). Apple non accetta altre curve.

Gestisco più organizzazioni Apple Ads

Collega ciascuna in un proprio profilo Hermoso. Una connessione è vincolata a una sola organizzazione, ed è ciò che impedisce che la campagna di un'agenzia finisca nell'account sbagliato del cliente.

Cosa può fare il connettore Apple Search Ads

Creare: create_apple_ads_campaign, create_apple_ads_ad_group, add_apple_ads_keywords, add_apple_ads_negative_keywords, update_apple_ads_object, set_apple_ads_status, delete_apple_ads_object.

Leggere: list_apple_ads_campaigns (stato, stato di pubblicazione, budget giornaliero e totale, i paesi in cui una campagna va in onda e il motivo indicato da Apple quando non può andare in onda), list_apple_ads_ad_groups (offerta predefinita e se Search Match è attivo), list_apple_ads_keywords (targeting e negative, con tipo di corrispondenza e offerta), apple_ads_report (impression, tap, installazioni, spesa, TTR, CPT e CPA a livello di campagna, gruppo di annunci, parola chiave, termine di ricerca o annuncio) e list_apple_ads_orgs.

Tutto questo è richiamabile da Claude, Claude Code, Codex, Cursor, Cline, OpenClaw, Hermes o qualunque altro client MCP, e dallo studio web. È lo stesso motore in entrambi i casi. Vedi la panoramica MCP o il riferimento degli strumenti pubblicitari.

E non solo: crea creatività e annunci (create_apple_ads_creative, create_apple_ads_ad), carica fino a 1.000 parole chiave in una sola chiamata (bulk_apple_ads_keywords) e legge i dati dello stesso Apple: apple_ads_keyword_suggestions, apple_ads_impression_share, apple_ads_search_term_popularity e apple_ads_change_history. Ognuno di questi è richiamabile dalla stessa chat.

Esportare i dati di Apple Search Ads

La stessa connessione produce report. apple_ads_report estrae le prestazioni di campagne, gruppi di annunci, annunci, parole chiave e termini di ricerca (impression, tap, installazioni, spesa, tasso di tap, costo per tap e costo per acquisizione), sia come totali sia come serie oraria, giornaliera, settimanale o mensile, fino a 5.000 righe per pagina. Leggere un report non tocca mai la spesa. Dove finiscono poi le righe dipende da te, e i tre posti più comuni sono qui sotto. La guida completa è Esportare i dati da Apple Search Ads.

Collegare Apple Search Ads a Google Sheets

Collega Google Drive insieme ad Apple Ads (una sola autorizzazione Google copre Drive, Sheets e Docs) e chiedi al tuo agente di mettere il report in un foglio. Chiama apple_ads_report, poi create_sheet per un nuovo foglio di calcolo oppure append_to_sheet per aggiungere le righe di questa settimana a uno esistente. Hermoso usa lo scope drive.file di Google, quindi raggiunge solo i file che ha creato o che hai scelto tu. Passo per passo: Collegare Apple Search Ads a Google Sheets.

Esportare Apple Search Ads in Looker Studio

Hermoso non ha un connettore nativo per Looker Studio. Looker Studio legge i Google Sheet con il suo connettore integrato, quindi il foglio qui sopra fa da ponte: aggiungilo una volta come origine dati Google Sheets, costruisci la dashboard e ogni aggiunta settimanale comparirà al prossimo aggiornamento. Power BI e Tableau leggono lo stesso foglio allo stesso modo. I passaggi per Looker Studio.

Esportare Apple Search Ads in JSON

Per le righe grezze, richiama lo strumento tramite l'API REST di Hermoso con una chiave API: POST https://app.hermoso.ai/v1/tools/apple_ads_report con gli argomenti del report come corpo JSON, e leggi le righe da data.rows nella risposta. Da terminale, npx -y hermoso call apple_ads_report --json '{...}' --structured stampa lo stesso risultato in JSON. Un esempio completo di richiesta.

Domande frequenti

Come collego Apple Search Ads a Claude?

Aggiungi Hermoso a Claude come connettore personalizzato con l'URL https://app.hermoso.ai/mcp e approvalo con il tuo account Hermoso, poi collega Apple Ads in Hermoso da Impostazioni › Connettori. Claude può quindi creare report, modificare e costruire le tue campagne Apple Search Ads tramite gli strumenti Apple Ads di Hermoso.

ChatGPT può leggere i miei dati di Apple Search Ads?

Sì. Aggiungi https://app.hermoso.ai/mcp in ChatGPT da Plugins › Add › Create MCP App, e collega Apple Ads in Hermoso. ChatGPT può poi estrarre impression, tap, installazioni, spesa, TTR, CPT e CPA per campagna, gruppo di annunci, annuncio, parola chiave o termine di ricerca, e scrivere le righe in un Google Sheet.

Esiste un server MCP per Apple Search Ads?

Sì. Il server MCP ospitato di Hermoso su https://app.hermoso.ai/mcp espone l'intero set di strumenti Apple Ads a Claude, ChatGPT, Cursor, Codex o qualunque client MCP: report, campagne, gruppi di annunci, parole chiave e negative, creatività e annunci, e i suggerimenti di parole chiave di Apple. Tutto ciò che crea parte in pausa.

Perché nella pagina API di Apple Ads non c'è il campo Public Key?

Perché sei connesso come Account Admin. Apple mostra quel campo solo a un utente con un ruolo API. Un amministratore vede invece una tabella “Manage API Access” con i fornitori di servizi terzi, senza alcun campo per la chiave in tutta la pagina. Invitati come API Account Manager in Account Settings › User Management, accedi come quell'utente, e il campo compare.

Quale ruolo Apple Ads mi serve?

API Account Manager se vuoi che Hermoso crei campagne, gruppi di annunci e parole chiave. Apple lo descrive come “accesso in lettura e scrittura a tutti i gruppi di campagne per la gestione tramite API”. API Account Read Only basta se ti interessano solo i report. Gli altri quattro ruoli che Apple offre (Account Admin, Account Finance, Account Read Only e Limited Access) non possono creare credenziali API.

Devo eseguire openssl?

No. Le istruzioni di Apple ti danno due comandi openssl; Hermoso genera la coppia di chiavi EC P-256 per te e ti mostra solo la metà pubblica. La metà privata è quella che firma le tue richieste, e non la vedi, non la incolli e non la memorizzi. Se hai già una chiave generata con un altro strumento, puoi portarla tu.

Collegare Apple Ads costa qualcosa o rischia la spesa?

No. Le letture si possono chiamare gratis, e ogni oggetto che Hermoso crea parte in pausa senza eccezioni. Attivare un oggetto è l'unico interruttore che fa partire la spesa reale, e richiede una conferma esplicita.

Cosa sono clientId, teamId e keyId?

I tre identificativi che Apple mostra sopra il campo Public Key una volta salvata la chiave. Identificano il tuo utente API presso Apple; la chiave privata dimostra che sei davvero tu. Incollali tutti e tre in Hermoso e la connessione è completa.

Una sola connessione può coprire più organizzazioni Apple Ads?

Una connessione è vincolata alla singola organizzazione che scegli quando la crei. Apple tratta un orgId un po' come un gruppo di campagne, quindi un solo accesso può coprire più organizzazioni. Un'agenzia con un cliente per ogni organizzazione collega ciascuna nel proprio profilo Hermoso.

Devo ruotare la chiave ogni 180 giorni?

No. Apple limita il client secret a 180 giorni, ed è per questo che le sue istruzioni ti chiedono di segnare in agenda una rotazione. Hermoso custodisce la chiave privata e genera un secret nuovo e a breve scadenza per ogni scambio di token, quindi non c'è nulla in un file di configurazione che possa scadere.

Posso esportare i dati di Apple Search Ads in Google Sheets o Looker Studio?

Sì. Collega Google Drive insieme ad Apple Ads, e il tuo agente scrive il report in un Google Sheet con create_sheet o append_to_sheet. Hermoso non ha un connettore nativo per Looker Studio; Looker Studio legge quel foglio con il proprio connettore Google Sheets.

Posso ottenere i dati di Apple Search Ads in JSON?

Sì. Richiama POST /v1/tools/apple_ads_report sull'API di Hermoso con una chiave API e leggi data.rows, oppure esegui hermoso call apple_ads_report con --structured dalla CLI.