Apple Search Ads koppelen aan Claude of ChatGPT in vijf minuten

De Hermoso-connector voor Apple Search Ads koppelt je Apple Ads-account aan Claude, ChatGPT, Cursor, de CLI of gewone HTTP, zodat een agent je App Store-zoekadvertenties voor je kan draaien. Hij bouwt de campagne, de advertentiegroep, de targeting-zoekwoorden en de negatieve zoekwoorden, leest terug wat Apple werkelijk heeft opgeslagen, en rapporteert de prestaties tot op het zoekwoord dat iemand typte voordat hij de app installeerde. Alles wat hij aanmaakt wordt gepauzeerd aangemaakt, en het inschakelen van uitgaven is een aparte stap die je expliciet bevestigt. Rapporten kunnen in een Google Sheet, een Looker Studio-dashboard of een JSON-bestand terechtkomen, en de pagina over de Apple Ads MCP laat zien wat de connector allemaal kan.

Koppelen duurt ongeveer vijf minuten. Je hoeft geen openssl te draaien, en er gaat geen Apple-wachtwoord naar Hermoso.

Apple Search Ads koppelen aan Claude

Om Apple Search Ads aan Claude te koppelen, voeg je Hermoso toe als connector in Claude en koppel je daarna je Apple Ads-account één keer in Hermoso. Open in Claude Customize › Connectors › Add custom connector, geef het de naam Hermoso, plak https://app.hermoso.ai/mcp en keur het goed met je Hermoso-account. Je hoeft geen sleutel in Claude te plakken. Koppel daarna Apple Ads in Hermoso onder Instellingen › Connectoren, met de stappen verderop op deze pagina. Vanaf dat moment kan Claude elke Apple Ads-tool van Hermoso aanroepen: vraag gewoon in je eigen woorden om een rapport, een zoekwoordwijziging of een nieuwe campagne. In Claude Code zijn het twee commando's: /plugin marketplace add hermoso-ai/hermoso, en dan /plugin install hermoso@hermoso. Hermoso in Claude beschrijft de volledige stappen.

Apple Search Ads koppelen aan ChatGPT

ChatGPT werkt op dezelfde manier. Open in ChatGPT Plugins, dan Add › Create MCP App, geef het de naam Hermoso, plak https://app.hermoso.ai/mcp als Server URL, laat Authentication op OAuth staan en keur het goed met je Hermoso-account. Als Create MCP App er niet staat, zet dan eenmalig Developer mode aan onder Settings › Plugins › Developer mode. Met Apple Ads gekoppeld in Hermoso kan ChatGPT je zoekwoordrapport ophalen, het in een Google Sheet zetten of een campagne voor je klaarzetten om na te kijken. Hermoso in ChatGPT loopt het stap voor stap door.

Cursor, Codex en elke andere MCP-client

Elke client die het Model Context Protocol spreekt, bereikt dezelfde tools op hetzelfde adres. Cursor leest https://app.hermoso.ai/mcp uit zijn mcp.json; Codex neemt de Hermoso-plugin met codex plugin marketplace add hermoso-ai/hermoso, die dezelfde tools vanuit de terminal aanstuurt. Welke client je ook gebruikt, je Apple-gegevens gaan nooit door de chat. De agent roept de tools van Hermoso aan, en Hermoso ondertekent elk verzoek aan Apple met de sleutel die het bewaart. De pagina over de Apple Ads MCP toont elke tool.

Wat je kunt vragen als het gekoppeld is

• “Haal de Apple Search Ads-prestaties van vorige week op per zoekwoord en laat me de tien zien met de hoogste kosten per acquisitie.”
• “Zet de uitgaven, installs en CPA van de afgelopen 30 dagen per campagne in een nieuwe Google Sheet met de naam Apple Ads.” (Koppel eerst Google Drive.)
• “Welke zoektermen hebben deze maand installs opgeleverd in mijn US-campagne waar ik nog niet op bied als exacte zoekwoorden?”
• “Voeg ‘budget planner’ en ‘expense tracker’ toe als exacte zoekwoorden in de Brand-advertentiegroep, en ‘jobs’ als negatief zoekwoord.”
• “Welke zoekwoorden stelt Apple voor mijn app voor, en welk aandeel van de vertoningen krijg ik op de zoekwoorden waarop ik al bied?”
• “Bouw een gepauzeerde campagne voor mijn app in het Verenigd Koninkrijk met een dagbudget van 50 dollar, en laat me daarna zien wat Apple heeft opgeslagen.”

Een rapport lezen raakt nooit je uitgaven aan. Alles wat de agent bouwt wordt gepauzeerd aangemaakt, en de schakelaar die de uitgaven aanzet wacht op jouw expliciete bevestiging.

Eerst het ding waar de meeste mensen op vastlopen

Apple's eigen instructie zegt: “Kies in de Ads UI Account Settings › API. Plak de sleutel in het veld Public Key.”

Dat veld bestaat niet voor een Account Admin. Log in als admin op je eigen account, open Account Settings › API, en dan zie je een tabel met de kop Manage API Access (een lijst met externe serviceproviders en één actie, Remove Access) en nergens op de pagina een sleutelveld. Het ziet eruit als een ontbrekende functie, en daarom stoppen mensen hier en concluderen ze dat de API voor hen niet beschikbaar is.

Hij is wel beschikbaar. Het Public Key-veld hoort bij een gebruiker met een API-rol, en accountadmin zijn is geen API-rol. In de uitnodigingsdialoog van Apple staan zes rollen, waarvan er precies twee API-rollen zijn:

• API Account Manager: “lees- en schrijftoegang tot alle campagnegroepen voor API-beheer”. Dit is degene die je kiest als je wilt dat Hermoso campagnes bouwt, niet alleen rapporteert.
• API Account Read Only: “alleen-lezen toegang tot alle campagnegroepen voor API-beheer”. Genoeg voor rapportage, en verder niets.

De andere vier (Account Admin, Account Finance, Account Read Only en Limited Access) kunnen helemaal geen API-inloggegevens aanmaken. De oplossing is dus een uitnodiging die je aan jezelf stuurt:

1. Open Account Settings › User Management en kies Invite Users.
2. Nodig een adres uit dat je beheert (je eigen adres, of een gedeeld adres zoals ads-api@yourcompany.com, zodat de inloggegevens een persoon overleven) met de rol API Account Manager.
3. Accepteer de uitnodiging vanuit die inbox en log daarna in op Apple Ads als die gebruiker.

Nu heeft Account Settings › API een Public Key-veld.

De koppeling, stap voor stap

1. Start hem in Hermoso. Instellingen › Connectoren › Apple Ads › Verbinden. Hermoso maakt een EC P-256-ondertekeningssleutel aan (dezelfde prime256v1-sleutel die Apple's twee openssl-commando's zouden hebben opgeleverd) en toont alleen de publieke helft. Kopieer die.
2. Geef de publieke helft aan Apple. Open als gebruiker met de API-rol Account Settings › API, plak hem in Public Key en klik op Save.
3. Kopieer de drie ids terug. Apple toont nu clientId, teamId en keyId boven dat veld. Alle drie.
4. Rond het af in Hermoso. Plak de drie ids en sla op. Hermoso wisselt een token met Apple en leest je organisatielijst voordat er iets wordt opgeslagen. Een verkeerd overgetypt id faalt dus meteen, terwijl je nog ziet wat je plakte, en niet pas bij je eerste rapport een uur later.
5. Kies de organisatie, als je inloggegevens meer dan één organisatie dekken. De koppeling wordt vastgezet op degene die je kiest.

Als er iets misgaat

Er is geen Public Key-veld op de API-pagina

Je bent ingelogd als Account Admin, of als een van de vier niet-API-rollen. Nodig jezelf uit als API Account Manager en log in als die gebruiker (zie hierboven). Dit is de enige meest voorkomende reden waarom een Apple Ads-koppeling nooit tot stand komt.

Apple wijst de inloggegevens af

De drie ids moeten bij de sleutel horen die Apple vasthoudt. Kopieer clientId, teamId en keyId opnieuw, vlak boven het Public Key-veld, en niet van een oudere sleutel die je hebt vervangen. Als het dan nog faalt, start de koppeling opnieuw in Hermoso: dat maakt een nieuw sleutelpaar aan, en dan plak je de nieuwe publieke helft in Apple.

De installatiesessie is verlopen

Hermoso houdt de gegenereerde privésleutel 24 uur vast terwijl je naar Apple gaat om de publieke helft te plakken. Daarna is hij weg, bewust. Start de koppeling opnieuw en plak de nieuwe publieke sleutel.

Ik heb al een sleutel met openssl gemaakt

Gebruik die dan. Plak je bestaande EC P-256-privésleutel bij het koppelen in plaats van die van Hermoso, en de publieke sleutel die al in je Apple-account staat blijft werken. Het moet een EC P-256 (prime256v1) sleutel zijn. Apple accepteert geen andere curve.

Ik beheer meerdere Apple Ads-organisaties

Koppel elke organisatie in een eigen Hermoso-profiel. Een koppeling is vastgezet op één organisatie, en dat voorkomt dat de campagne van een bureau in het account van de verkeerde klant terechtkomt.

Wat de Apple Search Ads-connector kan

Bouwen: 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.

Lezen: list_apple_ads_campaigns (status, bezorgstatus, dagelijks en totaal budget, de landen waarin een campagne draait, en Apple's eigen reden wanneer er niet kan worden gedraaid), list_apple_ads_ad_groups (standaardbod, en of Apple's Search Match aan staat), list_apple_ads_keywords (targeting en negatief, met matchtype en bod), apple_ads_report (vertoningen, taps, installs, uitgaven, TTR, CPT en CPA, op campagne-, advertentiegroep-, zoekwoord-, zoekterm- of advertentieniveau) en list_apple_ads_orgs.

Dit alles is aanroepbaar vanuit Claude, Claude Code, Codex, Cursor, Cline, OpenClaw, Hermes of elke andere MCP-client, en vanuit de webstudio. Het is in beide gevallen dezelfde engine. Zie de MCP-overzichtspagina of de referentie van de advertentietools.

En meer: het bouwt creatives en advertenties (create_apple_ads_creative, create_apple_ads_ad), laadt tot 1.000 zoekwoorden in één aanroep (bulk_apple_ads_keywords), en leest de eigen data van Apple: apple_ads_keyword_suggestions, apple_ads_impression_share, apple_ads_search_term_popularity en apple_ads_change_history. Elk daarvan is aanroepbaar vanuit dezelfde chat.

Gegevens exporteren uit Apple Search Ads

Dezelfde koppeling levert rapporten. apple_ads_report haalt de prestaties op van campagne, advertentiegroep, advertentie, zoekwoord en zoekterm (vertoningen, taps, installs, uitgaven, tap-through rate, kosten per tap en kosten per acquisitie), als totalen of als reeks per uur, dag, week of maand, tot 5.000 rijen per pagina. Een rapport lezen raakt nooit je uitgaven aan. Waar de rijen daarna heen gaan, bepaal jij, en de drie meest gebruikelijke plekken staan hieronder. De volledige gids is Gegevens exporteren uit Apple Search Ads.

Apple Search Ads koppelen aan Google Sheets

Koppel daarna Google Drive naast Apple Ads (één Google-autorisatie dekt Drive, Sheets en Docs) en vraag je agent het rapport in een spreadsheet te zetten. Hij roept apple_ads_report aan, daarna create_sheet voor een nieuwe spreadsheet of append_to_sheet om de rijen van deze week aan een bestaande toe te voegen. Hermoso gebruikt de drive.file-scope van Google, dus het bereikt alleen bestanden die het zelf heeft gemaakt of die jij hebt gekozen. Stap voor stap: Apple Search Ads koppelen aan Google Sheets.

Apple Search Ads exporteren naar Looker Studio

Hermoso heeft geen eigen Looker Studio-connector. Looker Studio leest Google Sheets met zijn eigen connector, dus de spreadsheet hierboven is de brug: voeg hem één keer toe als Google Sheets-databron, bouw het dashboard, en elke wekelijkse aanvulling verschijnt bij de volgende vernieuwing. Power BI en Tableau lezen dezelfde spreadsheet op dezelfde manier. De stappen voor Looker Studio.

Apple Search Ads exporteren naar JSON

Voor ruwe rijen roep je de tool aan via de Hermoso REST API met een API-sleutel: POST https://app.hermoso.ai/v1/tools/apple_ads_report met de rapportargumenten als JSON-body, en lees de rijen uit data.rows in het antwoord. Vanuit een terminal geeft npx -y hermoso call apple_ads_report --json '{...}' --structured hetzelfde resultaat als JSON. Een volledig voorbeeldverzoek.

Veelgestelde vragen

Hoe koppel ik Apple Search Ads aan Claude?

Voeg Hermoso toe aan Claude als custom connector met de URL https://app.hermoso.ai/mcp en keur het goed met je Hermoso-account. Koppel daarna Apple Ads in Hermoso onder Instellingen › Connectoren. Claude kan dan je Apple Search Ads-campagnes rapporteren, bewerken en bouwen via de Apple Ads-tools van Hermoso.

Kan ChatGPT mijn Apple Search Ads-data lezen?

Ja. Voeg https://app.hermoso.ai/mcp toe in ChatGPT onder Plugins › Add › Create MCP App en koppel Apple Ads in Hermoso. ChatGPT kan dan vertoningen, taps, installs, uitgaven, TTR, CPT en CPA ophalen per campagne, advertentiegroep, advertentie, zoekwoord of zoekterm, en de rijen in een Google Sheet zetten.

Is er een Apple Search Ads MCP-server?

Ja. De gehoste MCP-server van Hermoso op https://app.hermoso.ai/mcp stelt de volledige Apple Ads-toolset beschikbaar aan Claude, ChatGPT, Cursor, Codex of elke MCP-client: rapportage, campagnes, advertentiegroepen, zoekwoorden en negatieve zoekwoorden, creatives en advertenties, en de zoekwoordsuggesties van Apple. Alles wat het bouwt wordt gepauzeerd aangemaakt.

Waarom is er geen Public Key-veld op de Apple Ads API-pagina?

Omdat je bent ingelogd als Account Admin. Apple toont dat veld alleen aan een gebruiker met een API-rol. Een admin ziet in plaats daarvan een tabel “Manage API Access” met externe serviceproviders, zonder sleutelveld ergens op de pagina. Nodig jezelf uit als API Account Manager onder Account Settings › User Management, log in als die gebruiker, en het veld is er.

Welke Apple Ads-rol heb ik nodig?

API Account Manager als je wilt dat Hermoso campagnes, advertentiegroepen en zoekwoorden bouwt. Apple omschrijft die als “lees- en schrijftoegang tot alle campagnegroepen voor API-beheer”. API Account Read Only is genoeg als je alleen rapportage wilt. De andere vier rollen die Apple aanbiedt (Account Admin, Account Finance, Account Read Only en Limited Access) kunnen helemaal geen API-inloggegevens aanmaken.

Moet ik openssl draaien?

Nee. Apple's eigen instructies geven je twee openssl-commando's; Hermoso genereert het EC P-256-sleutelpaar voor je en toont alleen de publieke helft. De privéhelft is wat je verzoeken ondertekent, en die zie, plak of bewaar je nooit. Als je al een sleutel uit een ander hulpmiddel hebt, kun je die in plaats daarvan meegeven.

Kost het koppelen van Apple Ads iets, of riskeer ik uitgaven?

Nee. De leesacties zijn gratis om aan te roepen, en elk object dat Hermoso aanmaakt wordt GEPAUZEERD aangemaakt, zonder uitzondering. Een object inschakelen is de enige schakelaar die echte uitgaven activeert, en die vraagt om een expliciete bevestiging.

Wat zijn clientId, teamId en keyId?

De drie identificaties die Apple boven het Public Key-veld toont zodra je je sleutel opslaat. Ze identificeren je API-gebruiker bij Apple; de privésleutel bewijst dat jij het bent. Plak alle drie terug in Hermoso en de koppeling is klaar.

Kan één koppeling meerdere Apple Ads-organisaties dekken?

Een koppeling is vastgezet op de ene organisatie die je kiest bij het maken ervan. Apple behandelt een orgId een beetje als een campagnegroep, dus één login kan er meerdere dekken. Een bureau met een klant per organisatie koppelt elke organisatie in een eigen Hermoso-profiel.

Moet ik de sleutel elke 180 dagen roteren?

Nee. Apple beperkt een clientgeheim tot 180 dagen, en daarom laat Apple's eigen instructie je een rotatie in je agenda zetten. Hermoso bewaart de privésleutel en maakt voor elke tokenwisseling een nieuw kortlevend geheim, dus er staat niets in een configuratiebestand dat kan verlopen.

Kan ik Apple Search Ads-data naar Google Sheets of Looker Studio exporteren?

Ja. Koppel Google Drive naast Apple Ads en je agent schrijft het rapport met create_sheet of append_to_sheet in een Google Sheet. Hermoso heeft geen eigen Looker Studio-connector; Looker Studio leest die spreadsheet met zijn eigen Google Sheets-connector.

Kan ik Apple Search Ads-data als JSON krijgen?

Ja. Roep POST /v1/tools/apple_ads_report aan op de Hermoso API met een API-sleutel en lees data.rows, of draai hermoso call apple_ads_report met --structured vanuit de CLI.