اتصال Apple Search Ads در Hermoso حساب Apple Ads شما را به Claude، ChatGPT، Cursor، CLI یا HTTP ساده وصل میکند تا یک عامل بتواند کمپینهای جستجوی App Store شما را برایتان اجرا کند. این عامل کمپین، گروه آگهی، کلمات کلیدی هدف و کلمات منفی را میسازد، آنچه را Apple واقعاً ذخیره کرده دوباره می‌خواند، و عملکرد را تا سطح عبارت جستجویی گزارش میدهد که کاربری پیش از نصب تایپ کرده است. هر چیزی که ساخته میشود در حالت متوقف (paused) ساخته میشود و فعالکردن هزینه مرحله‌ای جداگانه است که تأیید صریح میخواهد. گزارش‌ها می‌توانند به یک Google Sheet، داشبورد Looker Studio یا فایل JSON بروند، و صفحهٔ MCP مربوط به Apple Ads همهٔ کارهایی را که این connector انجام میدهد فهرست میکند.
اتصال حدود پنج دقیقه طول می‌کشد. شما openssl اجرا نمیکنید و هیچ رمز عبور Apple به Hermoso نمی‌رسد.
اتصال Apple Search Ads به Claude
برای اتصال Apple Search Ads به Claude، Hermoso را بهعنوان connector به Claude اضافه کنید، سپس حساب Apple Ads خود را یک‌بار داخل Hermoso وصل کنید. در Claude گزینهٔ Customize › Connectors › Add custom connector را باز کنید، نام آن را Hermoso بگذارید، آدرس https://app.hermoso.ai/mcp را بچسبانید و با حساب Hermoso خود تأیید کنید. برای Claude هیچ کلیدی لازم نیست وارد کنید. سپس Apple Ads را در Hermoso زیر Settings › Connectors وصل کنید، با مراحلی که در ادامهٔ همین صفحه آمده است. از آن به بعد Claude میتواند هر ابزار Apple Ads موجود در Hermoso را صدا بزند: گزارش، تغییر کلمه کلیدی یا کمپین جدید را با زبان ساده بخواهید. در Claude Code بهجای این، دو دستور لازم است: /plugin marketplace add hermoso-ai/hermoso و سپس /plugin install hermoso@hermoso. Hermoso در Claude مراحل کامل را دارد.
اتصال Apple Search Ads به ChatGPT
ChatGPT همین‌طور کار میکند. در ChatGPT گزینهٔ Plugins را باز کنید، سپس Add › Create MCP App، نام Hermoso را بگذارید، آدرس https://app.hermoso.ai/mcp را بهعنوان Server URL وارد کنید، Authentication را روی OAuth نگه دارید و با حساب Hermoso خود تأیید کنید. اگر Create MCP App دیده نمی‌شود، یک‌بار Developer mode را زیر Settings › Plugins › Developer mode روشن کنید. وقتی Apple Ads در Hermoso وصل باشد، ChatGPT میتواند گزارش کلمات کلیدی شما را بکشد، آن را در یک Google Sheet بنویسد، یا یک کمپین پیش‌نویس کند تا شما بررسی کنید. Hermoso در ChatGPT را توضیح میدهد.
Cursor، Codex و هر کلاینت MCP دیگر
هر کلاینتی که Model Context Protocol را پشتیبانی کند، به همان ابزارها در همان آدرس می‌رسد. Cursor آدرس https://app.hermoso.ai/mcp را از فایل mcp.json خود می‌خواند؛ Codex افزونهٔ Hermoso را با codex plugin marketplace add hermoso-ai/hermoso می‌گیرد که همان ابزارها را از ترمینال اجرا میکند. هر کلاینتی که استفاده کنید، اعتبارنامه‌های Apple شما هرگز از گفتگو عبور نمی‌کند. عامل ابزارهای Hermoso را صدا می‌زند و Hermoso هر درخواست به Apple را با کلیدی که نگه می‌دارد امضا میکند. صفحهٔ MCP مربوط به Apple Ads همهٔ ابزارها را فهرست میکند.
چه چیزی بپرسید وقتی اتصال برقرار شد
- “عملکرد Apple Search Ads هفتهٔ گذشته را بر اساس کلمه کلیدی بکش و ده مورد با بالاترین هزینهٔ هر نصب (CPA) را نشانم بده.”
- “هزینه، نصب‌ها و CPA ۳۰ روز گذشته را بر اساس کمپین در یک Google Sheet جدید به نام Apple Ads بگذار.” (ابتدا Google Drive را وصل کنید.)
- “کدام عبارت‌های جستجو در این ماه در کمپین US من نصب آورده‌اند و هنوز به‌صورت کلمهٔ کلیدی دقیق روی آنها پیشنهاد قیمت نمی‌دهم؟”
- “‘budget planner’ و ‘expense tracker’ را بهعنوان کلمهٔ کلیدی دقیق در گروه Brand اضافه کن، و ‘jobs’ را بهعنوان کلمهٔ منفی.”
- “Apple چه کلمات کلیدی‌ای را برای اپ من پیشنهاد میکند، و سهم نمایش من روی کلماتی که از قبل پیشنهاد قیمت می‌دهم چقدر است؟”
- “یک کمپین متوقف برای اپ من در بریتانیا با بودجهٔ روزانهٔ ۵۰ دلار بساز، سپس نشانم بده Apple چه چیزی را ذخیره کرده.”
خواندن گزارش هیچ‌وقت به هزینه دست نمی‌زند. هر چیزی که عامل میسازد در حالت متوقف ساخته میشود، و کلید روشن‌کردن هزینه منتظر تأیید صریح شماست.
اول، چیزی که بیشتر افراد را متوقف میکند
دستورالعمل خود Apple می‌گوید: “از Ads UI گزینهٔ Account Settings › API را انتخاب کنید. کلید را در فیلد Public Key بچسبانید.”
آن فیلد برای ادمین حساب وجود ندارد. وقتی با حساب ادمین خودتان وارد شوید و Account Settings › API را باز کنید، جدولی با عنوان Manage API Access می‌بینید (فهرستی از ارائهدهندگان خدمات شخص ثالث با یک عملیات Remove Access) و هیچ فیلد کلیدی در کل صفحه نیست. این دقیقاً شبیه یک قابلیت گم‌شده به نظر می‌رسد، و به همین دلیل مردم همین‌جا می‌ایستند و نتیجه می‌گیرند که API برایشان در دسترس نیست.
در دسترس است. فیلد Public Key متعلق به کاربری است که نقش API دارد، و ادمین حساب بودن آن نقش نیست. دیالوگ دعوت Apple شش نقش ارائه میدهد که دقیقاً دو تای آن نقش API است:
- API Account Manager: “دسترسی خواندن و نوشتن به همهٔ گروههای کمپین برای مدیریت API”. این را انتخاب کنید اگر میخواهید Hermoso کمپین بسازد، نه فقط گزارش بگیرد.
- API Account Read Only: “دسترسی فقط خواندنی به همهٔ گروههای کمپین برای مدیریت API”. برای گزارشگیری کافی است و غیر از آن کاری نمی‌کند.
چهار نقش دیگر (Account Admin، Account Finance، Account Read Only و Limited Access) اصلاً نمیتوانند اعتبارنامهٔ API بسازند. پس راه‌حل یک دعوت است که برای خودتان می‌فرستید:
- صفحهٔ Account Settings › User Management را باز کنید و Invite Users را انتخاب کنید.
- یک نشانی را دعوت کنید که کنترلش دست شماست (نشانی خودتان، یا یک نشانی مشترک مثل
ads-api@yourcompany.comتا اعتبارنامه از یک نفر جدا بماند) با نقش API Account Manager. - دعوت را از آن صندوق ایمیل بپذیرید، سپس Apple Ads را بهعنوان همان کاربر وارد کنید.
حالا در Account Settings › API یک فیلد Public Key وجود دارد.
اتصال، گام به گام
- در Hermoso شروع کنید. Settings › Connectors › Apple Ads › Connect. Hermoso یک کلید امضای EC P-256 میسازد (همان کلید
prime256v1که دو دستورopensslدر Apple می‌ساخت) و فقط نیمهٔ عمومی آن را نشان میدهد. آن را کپی کنید. - نیمهٔ عمومی را به Apple بدهید. بهعنوان کاربری با نقش API، Account Settings › API را باز کنید، آن را در Public Key بچسبانید و Save را بزنید.
- سه شناسه را برگردانید. Apple حالا
clientId،teamIdوkeyIdرا بالای آن فیلد نشان میدهد. هر سه را کپی کنید. - اتصال را در Hermoso تمام کنید. سه شناسه را بچسبانید و ذخیره کنید. Hermoso با Apple یک توکن مبادله میکند و فهرست سازمان‌های شما را قبل از ذخیرهٔ هر چیزی می‌خواند. پس شناسهٔ اشتباه همان‌جا رد میشود، در حالی که هنوز می‌بینید چه چیزی چسبانده‌اید، نه یک ساعت بعد در اولین گزارش.
- سازمان را انتخاب کنید، اگر اعتبارنامه‌های شما بیش از یک سازمان را پوشش میدهد. اتصال به سازمانی که انتخاب می‌کنید محدود میشود.
اگر مشکلی پیش آمد
روی صفحهٔ API هیچ فیلد Public Key نیست
شما با نقش Account Admin، یا یکی از چهار نقش غیر API وارد شدهاید. خودتان را بهعنوان API Account Manager دعوت کنید و با آن کاربر وارد شوید (بالاتر را ببینید). این شایع‌ترین دلیلی است که یک اتصال Apple Ads هرگز برقرار نمی‌شود.
Apple اعتبارنامه‌ها را رد میکند
سه شناسه باید متعلق به کلیدی باشند که Apple نگه داشته است. clientId، teamId و keyId را دوباره از بالای فیلد Public Key کپی کنید، نه از کلید قدیمی‌ای که جایگزینش کرده‌اید. اگر باز هم رد شد، اتصال را در Hermoso دوباره شروع کنید: این یک جفت کلید تازه میسازد و نیمهٔ عمومی جدید را در Apple بچسبانید.
جلسهٔ راه‌اندازی منقضی شد
Hermoso کلید خصوصی ساخته‌شده را ۲۴ ساعت نگه می‌دارد، تا وقتی نیمهٔ عمومی را به Apple می‌برید. بعد از آن عمداً حذف میشود. اتصال را دوباره شروع کنید و کلید عمومی تازه را بچسبانید.
قبلاً با openssl کلید ساخته‌ام
پس از همان استفاده کنید. هنگام اتصال، کلید خصوصی EC P-256 موجود خودتان را بهجای کلید Hermoso بچسبانید، و کلید عمومی‌ای که از قبل در حساب Apple شماست همچنان کار میکند. باید یک کلید EC P-256 (prime256v1) باشد. Apple هیچ منحنی دیگری نمی‌پذیرد.
چند سازمان Apple Ads را مدیریت می‌کنم
هر کدام را در پروفایل Hermoso جداگانه‌ای وصل کنید. یک اتصال به یک سازمان محدود است، و همین جلوی این را می‌گیرد که کمپین یک آژانس در حساب اشتباه مشتری بنشیند.
کارهایی که connector مربوط به Apple Search Ads انجام میدهد
ساختن: 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.
خواندن: list_apple_ads_campaigns (وضعیت، وضعیت ارائه، بودجهٔ روزانه و کل، کشورهایی که کمپین در آنها اجرا میشود، و دلیلی که خود Apple بیان میکند وقتی کمپینی نمی‌تواند اجرا شود)، list_apple_ads_ad_groups (پیشنهاد قیمت پیش‌فرض، و اینکه Search Match مربوط به Apple روشن است یا نه)، list_apple_ads_keywords (هدف‌گیری و منفی، با نوع تطبیق و پیشنهاد قیمت)، apple_ads_report (نمایش، تپ، نصب، هزینه، TTR، CPT و CPA در سطح کمپین، گروه آگهی، کلمه کلیدی، عبارت جستجو یا آگهی) و list_apple_ads_orgs.
همهٔ این‌ها از Claude، Claude Code، Codex، Cursor، Cline، OpenClaw، Hermes یا هر کلاینت MCP دیگری و همچنین از استودیوی وب قابل فراخوانیاند. در هر دو حالت همان موتور است. نمای کلی MCP یا مرجع ابزارهای تبلیغات را ببینید.
و بیشتر: این connector آگهیها و تبلیغات را میسازد (create_apple_ads_creative، create_apple_ads_ad)، تا ۱۰۰۰ کلمهٔ کلیدی را در یک فراخوانی بارگذاری میکند (bulk_apple_ads_keywords)، و داده‌های خود Apple را می‌خواند: apple_ads_keyword_suggestions، apple_ads_impression_share، apple_ads_search_term_popularity و apple_ads_change_history. هر یک از آنها از همان گفتگو قابل فراخوانی است.
صادرکردن داده از Apple Search Ads
همان اتصال گزارش هم میدهد. apple_ads_report عملکرد کمپین، گروه آگهی، آگهی، کلمه کلیدی و عبارت جستجو را می‌کشد (نمایش، تپ، نصب، هزینه، نرخ تپ، هزینهٔ هر تپ و هزینهٔ هر نصب)، به‌صورت جمع کل یا سری ساعتی، روزانه، هفتگی یا ماهانه، تا ۵۰۰۰ ردیف در هر صفحه. خواندن گزارش هیچ‌وقت به هزینه دست نمی‌زند. اینکه ردیف‌ها بعداً کجا بروند با شماست، و سه مقصد رایج‌تر در زیر آمده‌اند.
راهنمای کامل: صادرکردن داده از Apple Search Ads.
اتصال Apple Search Ads به Google Sheets
Google Drive را کنار Apple Ads وصل کنید (یک مجوز Google هم Drive، هم Sheets و هم Docs را پوشش میدهد) و از عامل بخواهید گزارش را در یک صفحه‌گسترده بگذارد. عامل apple_ads_report را صدا می‌زند، سپس create_sheet برای یک صفحهٔ جدید یا append_to_sheet برای افزودن ردیف‌های این هفته به یک صفحهٔ موجود. Hermoso از دامنهٔ دسترسی drive.file گوگل استفاده میکند، پس فقط به فایل‌هایی می‌رسد که خودش ساخته یا شما انتخاب کرده‌اید. گام به گام: اتصال Apple Search Ads به Google Sheets.
صادرکردن Apple Search Ads به Looker Studio
Hermoso connector بومی Looker Studio ندارد. Looker Studio صفحات گسترده گوگل را با connector داخلی خودش می‌خواند، پس صفحهٔ بالا پل ارتباطی است: آن را یک‌بار بهعنوان منبع داده Google Sheets اضافه کنید، داشبورد را بسازید، و هر افزودهٔ هفتگی در بازخوانی بعدی نمایش داده میشود. Power BI و Tableau هم همین صفحه را به همین شکل می‌خوانند. مراحل Looker Studio.
صادرکردن Apple Search Ads به JSON
برای ردیف‌های خام، ابزار را از طریق REST API Hermoso با یک کلید API صدا بزنید: POST https://app.hermoso.ai/v1/tools/apple_ads_report با آرگومان‌های گزارش بهعنوان بدنهٔ JSON، و ردیف‌ها را از data.rows در پاسخ بخوانید. از ترمینال، npx -y hermoso call apple_ads_report --json '{...}' --structured همان نتیجه را به‌صورت JSON چاپ میکند. یک نمونهٔ کامل درخواست.
پرسش‌های متداول
چگونه Apple Search Ads را به Claude وصل کنم؟
Hermoso را بهعنوان connector سفارشی در Claude با آدرس https://app.hermoso.ai/mcp اضافه کنید و با حساب Hermoso خود تأیید کنید، سپس Apple Ads را در Hermoso زیر Settings › Connectors وصل کنید. آنگاه Claude میتواند کمپینهای Apple Search Ads شما را از طریق ابزارهای Apple Ads Hermoso گزارش بدهد، ویرایش کند و بسازد.
آیا ChatGPT میتواند داده‌های Apple Search Ads مرا بخواند؟
بله. https://app.hermoso.ai/mcp را در ChatGPT زیر Plugins › Add › Create MCP App اضافه کنید و Apple Ads را در Hermoso وصل کنید. آنگاه ChatGPT میتواند نمایش، تپ، نصب، هزینه، TTR، CPT و CPA را بر اساس کمپین، گروه آگهی، آگهی، کلمه کلیدی یا عبارت جستجو بکشد، و ردیف‌ها را در یک Google Sheet بنویسد.
آیا سرور MCP برای Apple Search Ads وجود دارد؟
بله. سرور MCP میزبانیشدهٔ Hermoso در https://app.hermoso.ai/mcp کل مجموعه ابزارهای Apple Ads را برای Claude، ChatGPT، Cursor، Codex یا هر کلاینت MCP در دسترس میگذارد: گزارشگیری، کمپینها، گروههای آگهی، کلمات کلیدی و منفیها، کریتیو و آگهیها، و پیشنهادهای کلمات کلیدی Apple. هر چیزی که میسازد در حالت متوقف ساخته میشود.
چرا روی صفحهٔ API در Apple Ads فیلد Public Key نیست؟
چون با حساب Account Admin وارد شدهاید. Apple آن فیلد را فقط برای کاربری نشان میدهد که نقش API دارد. ادمین بهجای آن جدولی با عنوان “Manage API Access” از ارائهدهندگان خدمات شخص ثالث میبیند، بدون هیچ فیلد کلیدی در کل صفحه. زیر Account Settings › User Management خودتان را بهعنوان API Account Manager دعوت کنید، با آن کاربر وارد شوید، و فیلد آنجاست.
به کدام نقش Apple Ads نیاز دارم؟
API Account Manager اگر میخواهید Hermoso کمپینها، گروههای آگهی و کلمات کلیدی بسازد. Apple آن را “دسترسی خواندن و نوشتن به همهٔ گروههای کمپین برای مدیریت API” توصیف میکند. API Account Read Only اگر فقط گزارشگیری میخواهید کافی است. چهار نقش دیگری که Apple ارائه میدهد (Account Admin، Account Finance، Account Read Only و Limited Access) اصلاً نمیتوانند اعتبارنامهٔ API بسازند.
آیا باید openssl اجرا کنم؟
خیر. دستورالعمل خود Apple دو دستور openssl میدهد؛ Hermoso جفت کلید EC P-256 را برای شما میسازد و فقط نیمهٔ عمومی را نشان میدهد. نیمهٔ خصوصی همان چیزی است که درخواستهای شما را امضا میکند، و شما هرگز آن را نمیبینید، نمیچسبانید یا ذخیره نمیکنید. اگر از قبل کلیدی از ابزار دیگری دارید، میتوانید آن را بیاورید.
آیا اتصال Apple Ads هزینه دارد یا خطر هزینهٔ ناخواسته دارد؟
خیر. خواندنها آزادانه قابل فراخوانیاند، و هر شیئی که Hermoso بسازد با هیچ overrideای در حالت PAUSED ساخته میشود. فعالکردن شیء تنها کلیدی است که هزینهٔ واقعی را روشن میکند، و تأیید صریح میخواهد.
clientId، teamId و keyId چیستند؟
سه شناسهای که Apple بعد از ذخیرهٔ کلیدتان بالای فیلد Public Key چاپ میکند. آنها کاربر API شما را نزد Apple شناسایی میکنند؛ کلید خصوصی ثابت میکند که خود شما هستید. هر سه را به Hermoso برگردانید و اتصال کامل است.
آیا یک اتصال میتواند چند سازمان Apple Ads را پوشش دهد؟
یک اتصال به تنها سازمانی محدود است که هنگام ساختنش انتخاب می‌کنید. Apple با orgId مانند یک گروه کمپین رفتار میکند، پس یک ورود میتواند چند سازمان را پوشش دهد. آژانسی با یک کلاینت برای هر سازمان، هر کدام را در پروفایل Hermoso جداگانه‌ای وصل میکند.
آیا باید کلید را هر ۱۸۰ روز بچرخانم؟
خیر. Apple سقف یک client secret را ۱۸۰ روز گذاشته است، و به همین دلیل دستورالعمل‌های خود Apple یادآور چرخش را دارند. Hermoso کلید خصوصی را نگه می‌دارد و برای هر مبادلهٔ توکن یک secret کوتاه‌مدت تازه میسازد، پس چیزی در فایل پیکربندی نیست که منقضی شود.
آیا می‌توانم داده‌های Apple Search Ads را به Google Sheets یا Looker Studio صادر کنم؟
بله. Apple Ads و Google Drive را کنار هم وصل کنید، و عامل گزارش را با create_sheet یا append_to_sheet در یک صفحهٔ Google می‌نویسد. Hermoso connector بومی Looker Studio ندارد؛ Looker Studio آن صفحه را با connector Google Sheets خودش می‌خواند.
آیا می‌توانم داده‌های Apple Search Ads را به‌صورت JSON بگیرم؟
بله. POST /v1/tools/apple_ads_report را روی Hermoso API با یک کلید API صدا بزنید و data.rows را بخوانید، یا hermoso call apple_ads_report را با --structured از CLI اجرا کنید.
Apple Search Ads یازدهمین پلتفرم تبلیغاتی است که Hermoso روی آن کمپین میسازد و کمپینها را می‌خواند، کنار Meta، Google Ads، Microsoft Advertising، Reddit Ads، LinkedIn، Pinterest، X Ads، TikTok Ads، Snapchat Ads و ChatGPT Ads. پلن رایگان به کارت نیاز ندارد.
شروع رایگان → ← MCP & CLI