ربط Apple Search Ads مع Claude أو ChatGPT في خمس دقائق

يربط موصّل Hermoso لـ Apple Search Ads حساب Apple Ads الخاص بك مع Claude وChatGPT وCursor وCLI أو HTTP العادي، فيستطيع الوكيل تشغيل إعلانات البحث في App Store نيابةً عنك. يبني الحملة ومجموعة الإعلانات وكلمات الاستهداف والكلمات السلبية، ويقرأ ما خزّنته Apple فعلًا، ويعرض الأداء حتى عبارة البحث التي كتبها شخص قبل أن يثبّت التطبيق. كل ما ينشئه يُنشأ متوقفًا، وتفعيل الإنفاق خطوة منفصلة يجب تأكيدها صراحةً. يمكن أن تصل التقارير إلى جدول Google أو لوحة Looker Studio أو ملف JSON، وصفحة Apple Ads MCP تسرد كل ما يستطيع الموصّل فعله.

يستغرق الربط نحو خمس دقائق. لن تشغّل openssl، ولن تصل كلمة مرور Apple إلى Hermoso بأي حال.

ربط Apple Search Ads مع Claude

لربط Apple Search Ads مع Claude، أضف Hermoso إلى 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، أو إعداد حملة لتراجعها أنت. تشرح صفحة 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 بالمفتاح الذي يحتفظ به. تسرد صفحة Apple Ads MCP كل أداة.

ما الذي تطلبه بعد الربط

• “اعرض أداء Apple Search Ads للأسبوع الماضي حسب الكلمة المفتاحية، وأرني العشر الأعلى في تكلفة الاكتساب.”
• “ضع إنفاق الثلاثين يومًا الأخيرة والتثبيتات وCPA حسب الحملة في جدول Google جديد باسم Apple Ads.” (اربط Google Drive أولًا.)
• “ما عبارات البحث التي جلبت تثبيتات في حملتي الأمريكية هذا الشهر ولا أزايد عليها بمطابقة تامة بعد؟”
• “أضف ‘budget planner’ و‘expense tracker’ كمطابقة تامة في مجموعة الإعلانات Brand، وأضف ‘jobs’ كسلبية.”
• “ما الكلمات المفتاحية التي تقترحها Apple لتطبيقي، وما حصتي من الظهور في الكلمات التي أزايد عليها أصلًا؟”
• “أنشئ حملة متوقفة لتطبيقي في المملكة المتحدة بميزانية يومية 50 دولارًا، ثم أرني ما خزّنته Apple.”

قراءة التقرير لا تمسّ الإنفاق أبدًا. كل ما يبنيه الوكيل يُنشأ متوقفًا، ومفتاح تشغيل الإنفاق ينتظر تأكيدك الصريح.

أولًا، الأمر الذي يوقف معظم الناس

تقول تعليمات Apple: “من واجهة الإعلانات، اختر Account Settings › API. الصق المفتاح في حقل Public Key.”

هذا الحقل غير موجود لمدير الحساب. سجّل الدخول كمدير على حسابك الإعلاني، وافتح Account Settings › API، فسترى جدولًا عنوانه Manage API Access (قائمة بمزودي خدمات الطرف الثالث مع إجراء واحد هو Remove Access) ولا يوجد أي حقل مفتاح في الصفحة. يبدو الأمر كأن الميزة غير متاحة، ولهذا يتوقف الناس هنا ويستنتجون أن الواجهة البرمجية ليست متاحة لهم.

لكنها متاحة. حقل 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 أصلًا. لذلك فالحل دعوة ترسلها إلى نفسك:

1. افتح Account Settings › User Management واختر Invite Users.
2. ادعُ عنوانًا تتحكم فيه (عنوانك الشخصي، أو عنوانًا مشتركًا مثل ads-api@yourcompany.com حتى تبقى بيانات الاعتماد بعد رحيل أي شخص) بالدور API Account Manager.
3. اقبل الدعوة من ذلك البريد، ثم سجّل الدخول إلى Apple Ads بصفتك ذلك المستخدم.

الآن تظهر في Account Settings › API خانة Public Key.

الربط خطوة بخطوة

1. ابدأ الربط في Hermoso. Settings › Connectors › Apple Ads › Connect. يولّد Hermoso مفتاح توقيع من نوع EC P-256 (المفتاح prime256v1 نفسه الذي كان سينتجه أمرا openssl اللذان تطلبهما Apple) ويعرض لك النصف العام فقط. انسخه.
2. أعطِ النصف العام لـ Apple. بصفتك المستخدم صاحب دور API، افتح Account Settings › API، والصقه في Public Key، ثم اضغط Save.
3. انسخ المعرّفات الثلاثة إلى Hermoso. تعرض Apple الآن clientId وteamId وkeyId فوق تلك الخانة. انسخها كلها.
4. أنهِ الربط في Hermoso. الصق المعرّفات الثلاثة واحفظ. يتبادل Hermoso رمزًا مع Apple ويقرأ قائمة مؤسساتك قبل أن يخزّن أي شيء، فيفشل المعرّف الخاطئ في هذه اللحظة بينما ما زلت ترى ما لصقته، لا بعد ساعة عند أول تقرير لك.
5. اختر المؤسسة إذا غطّت بياناتك أكثر من مؤسسة واحدة. يرتبط الربط بالمؤسسة التي تختارها.

إذا حدث خطأ ما

لا يوجد حقل Public Key في صفحة API

أنت مسجّل الدخول كمدير Account Admin، أو بأحد الأدوار الأربعة غير الخاصة بـ API. ادعُ نفسك بدور API Account Manager وسجّل الدخول بذلك المستخدم (انظر أعلاه). هذا هو السبب الأكثر شيوعًا لعدم اكتمال ربط Apple Ads أبدًا.

ترفض Apple بيانات الاعتماد

يجب أن تنتمي المعرّفات الثلاثة إلى المفتاح الذي تحتفظ به Apple. أعد نسخ clientId وteamId وkeyId من الأعلى مباشرة فوق خانة Public Key، لا من مفتاح أقدم استبدلته. وإن ظلت تفشل، فابدأ الربط من جديد في Hermoso: ذلك يُنشئ زوج مفاتيح جديدًا، والصق النصف العام الجديد في Apple.

انتهت جلسة الإعداد

يحتفظ Hermoso بالمفتاح الخاص المولّد لمدة 24 ساعة بينما تذهب لتلصق نصفه العام في Apple. بعد ذلك يُمحى عمدًا. ابدأ الربط من جديد والصق المفتاح العام الجديد.

سبق أن أنشأت مفتاحًا بـ openssl

استخدمه إذن. الصق مفتاح EC P-256 الخاص الموجود لديك عند الربط بدلًا من مفتاح Hermoso، وسيستمر المفتاح العام المسجّل أصلًا في حساب Apple الخاص بك في العمل. يجب أن يكون المفتاح من نوع EC P-256 (prime256v1)، فلا تقبل Apple منحنى آخر.

أدير عدة مؤسسات في Apple Ads

اربط كل واحدة في ملف Hermoso شخصي خاص بها. يرتبط الربط بمؤسسة واحدة، وهذا ما يمنع وصول حملة أحد عملاء الوكالة إلى حساب عميل آخر.

ما الذي يستطيع موصّل 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 مفعّل)، وlist_apple_ads_keywords (الاستهداف والسلبية، مع نوع المطابقة والسعر)، وapple_ads_report (الظهور والنقرات والتثبيتات والإنفاق وTTR وCPT وCPA على مستوى الحملة أو مجموعة الإعلانات أو الإعلان أو الكلمة المفتاحية أو عبارة البحث)، وlist_apple_ads_orgs.

كل ذلك متاح من Claude وClaude Code وCodex وCursor وCline وOpenClaw وHermes أو أي عميل MCP آخر، ومن استوديو الويب. المحرك واحد في كل الحالات. انظر نظرة عامة على MCP أو مرجع أدوات الإعلانات.

وأكثر من ذلك: يبني الإبداعات والإعلانات (create_apple_ads_creative، create_apple_ads_ad)، ويحمّل حتى 1,000 كلمة مفتاحية في استدعاء واحد (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 أداء الحملة ومجموعة الإعلانات والإعلان والكلمة المفتاحية وعبارة البحث (الظهور والنقرات والتثبيتات والإنفاق ونسبة النقر وتكلفة النقرة وتكلفة الاكتساب)، سواء كمجاميع أو كسلسلة بالساعة أو اليوم أو الأسبوع أو الشهر، حتى 5,000 صف في الصفحة. قراءة التقرير لا تمسّ الإنفاق أبدًا. أما المكان الذي تذهب إليه الصفوف بعد ذلك فهو من اختيارك، وأكثر ثلاثة أماكن شيوعًا مذكورة أدناه. الدليل الكامل: تصدير البيانات من Apple Search Ads.

ربط Apple Search Ads بجداول Google

وصِل Google Drive بجانب Apple Ads (موافقة Google واحدة تغطي Drive وSheets وDocs)، واطلب من وكيلك وضع التقرير في جدول. يستدعي apple_ads_report، ثم create_sheet لجدول جديد أو append_to_sheet لإضافة صفوف هذا الأسبوع إلى جدول موجود. يطلب Hermoso نطاق Google drive.file، فلا يصل إلا إلى الملفات التي أنشأها أو اخترتها. الخطوات بالتفصيل: ربط Apple Search Ads بجداول Google.

تصدير Apple Search Ads إلى Looker Studio

لا يملك Hermoso موصّلًا أصليًا لـ Looker Studio، ونفضّل أن نقول ذلك بدلًا من أن نوحي بوجوده. ولا يحتاج إليه: فـ Looker Studio يقرأ جداول Google بموصله المدمج الخاص، فيكون الجدول أعلاه هو الجسر. أضفه مرة واحدة كمصدر بيانات من جداول Google، وابنِ اللوحة، وسيظهر كل تحديث أسبوعي في تحديث البيانات التالي. خطوات Looker Studio.

تصدير Apple Search Ads إلى JSON

للحصول على الصفوف الخام، استدعِ الأداة عبر واجهة Hermoso REST API بمفتاح 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 إلى 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 بعدها سحب الظهور والنقرات والتثبيتات والإنفاق ونسبة النقر وCPT وCPA حسب الحملة أو مجموعة الإعلانات أو الإعلان أو الكلمة المفتاحية أو عبارة البحث، وكتابة الصفوف في جدول Google.

هل يوجد خادم MCP لـ Apple Search Ads؟

نعم. يعرض خادم MCP المستضاف في Hermoso على https://app.hermoso.ai/mcp مجموعة أدوات Apple Ads كاملة لـ Claude وChatGPT وCursor وCodex أو أي عميل MCP: التقارير والحملات ومجموعات الإعلانات والكلمات المفتاحية والسلبيات والإبداعات والإعلانات واقتراحات الكلمات من Apple. كل ما يبنيه يُنشأ متوقفًا.

لماذا لا يوجد حقل Public Key في صفحة Apple Ads API؟

لأنك مسجّل الدخول كمدير Account Admin. لا تعرض Apple ذلك الحقل إلا لمستخدم يحمل دور API. يرى المدير بدلًا منه جدول “Manage API Access” لمزودي خدمات الطرف الثالث، دون أي حقل مفتاح في الصفحة. ادعُ نفسك بدور API Account Manager من Account Settings › User Management، وسجّل الدخول بذلك المستخدم، وسيظهر الحقل.

ما دور 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 يُنشأ متوقفًا دون أي تجاوز. تفعيل الكائن هو المفتاح الوحيد الذي يشغّل الإنفاق الحقيقي، ويتطلب تأكيدًا صريحًا.

ما هي clientId وteamId وkeyId؟

المعرّفات الثلاثة التي تطبعها Apple فوق خانة Public Key بعد أن تحفظ مفتاحك. تعرّف مستخدم API لديها؛ والمفتاح الخاص هو ما يثبت أنك أنت. الصقها كلها في Hermoso وينتهي الربط.

هل يستطيع ربط واحد أن يغطي عدة مؤسسات في Apple Ads؟

يرتبط الربط بالمؤسسة الواحدة التي تختارها عند إنشائه. تتعامل Apple مع orgId كما لو كان مجموعة حملات، فقد يغطي تسجيل دخول واحد أكثر من مؤسسة. الوكالة التي لديها عميل بكل مؤسسة تربط كل واحدة في ملف Hermoso شخصي خاص بها.

هل يجب أن أجدد المفتاح كل 180 يومًا؟

لا. تحدد Apple عمر السر العميل بـ180 يومًا، ولهذا تطلب تعليماتها منك أن تضع موعدًا للتجديد. يحتفظ Hermoso بالمفتاح الخاص ويولّد سرًا جديدًا قصير العمر مع كل تبادل رمز، فلا يوجد شيء في ملف إعدادات ينتهي صلاحيته.

هل يمكنني تصدير بيانات Apple Search Ads إلى جداول Google أو Looker Studio؟

نعم. وصِل Google Drive بجانب Apple Ads، ويكتب وكيلك التقرير في جدول Google باستخدام create_sheet أو append_to_sheet. لا يملك Hermoso موصلًا أصليًا لـ Looker Studio؛ بل تقرأ Looker Studio ذلك الجدول بموصل جداول Google الخاص بها.

هل يمكنني الحصول على بيانات Apple Search Ads بصيغة JSON؟

نعم. استدعِ POST /v1/tools/apple_ads_report على واجهة Hermoso API بمفتاح API واقرأ data.rows، أو شغّل hermoso call apple_ads_report مع --structured من CLI.