يتصل Hermoso بـ Apple Search Ads ويعرضه كأدوات يستطيع وكيلك استدعاءها: Claude وChatGPT وCursor وCodex وCline والطرفية أو HTTP العادي. يسحب apple_ads_report أداء الحملة ومجموعة الإعلانات والإعلان والكلمة المفتاحية وعبارة البحث، وتعود الصفوف كبيانات لا كملف CSV للتحميل تحتاج بعدها إلى نقله إلى مكان آخر.
موصّل Apple Search Ads
لا تنشر Apple أي تدفق OAuth لواجهة الإعلانات البرمجية، لذا فالربط تبادل مفاتيح لا زر: يولّد Hermoso مفتاح التوقيع، وتلصق نصفه العام في Apple Ads، وتعيد إليه ثلاثة معرّفات. يشرح دليل إعداد Apple Search Ads الخطوات، بما فيها حقل Public Key الذي لا يجده معظم الناس. ثم يخدم الربط الواحد تطبيق الويب وخادم MCP والطرفية وواجهة REST، فيعمل التصدير نفسه من Claude أو ChatGPT أو Cursor: اربط Apple Search Ads بـ Claude أو بـ ChatGPT مرة واحدة، ثم اسأل.
التقارير جزء من الصورة فقط. الربط نفسه يبني الحساب ويديره: الحملات ومجموعات الإعلانات والكلمات المفتاحية والسلبيات وأوامر الميزانية والاستهداف واقتراحات الكلمات وسجل التغييرات. تسرد صفحة قناة Apple Ads كل أداة.
ما الذي يحتويه التقرير
استدعاء واحد، خمسة مستويات. يُبلّغ apple_ads_report على مستوى الحملة أو مجموعة الإعلانات أو الإعلان أو الكلمة المفتاحية أو عبارة البحث، وكل صف يحمل المقاييس نفسها التي تعرضها لوحة Apple: الظهور والنقرات والتثبيتات والإنفاق ونسبة النقر وتكلفة النقرة وتكلفة الاكتساب. اطلب المجاميع، أو سلسلة بمستوى الساعة أو اليوم أو الأسبوع أو الشهر. تأتي الصفوف مرتبة حسب الإنفاق من الأعلى، حتى 5,000 صف في الصفحة، مع صف للمجاميع الكلية عند الطلب. وقد تتضمن تقارير App Store كيانات بلا أي ظهور، فتظهر الكلمة المتوقفة بصفر بدلًا من أن تختفي من السطور.
قاعدتان تفرضهما Apple، والأداة تشرحهما بدلًا من أن تفشل بصمت: التقرير الأدنى من مستوى الحملة يحتاج إلى معرّف حملة (فقط تقرير مستوى الحملة يغطي الحساب كله)، وتقارير عبارات البحث تعمل بالمنطقة الزمنية لمؤسستك، لا بالتوقيت العالمي أبدًا. وتغطي الإعلانات على خرائط Apple أيضًا: يأتي تقرير العلامات التجارية للأنشطة من الأداة نفسها مع تغيير معامل واحد.
ربط Apple Search Ads بجداول Google
هذه هي الوجهة الوحيدة التي يكتب فيها Hermoso بنفسه. وصِل Google Drive بجانب Apple Ads (موافقة Google واحدة تغطي Drive وSheets وDocs)، ثم اطلب: "اسحب أداء Apple Search Ads حسب الكلمة المفتاحية للأيام الثلاثين الأخيرة وضعه في جدول جديد باسم Apple Ads." يستدعي الوكيل apple_ads_report، ثم create_sheet، ويعيد إليك الرابط. في الأسبوع التالي، الطلب نفسه مع كلمة "append" يضيف صفوفًا عبر append_to_sheet بدلًا من أن يبدأ من جديد.
يطلب Hermoso من Google النطاق drive.file، الذي لا يصل إلا إلى الملفات التي أنشأها أو اخترتها، لا إلى Drive كله. الشرح الكامل، بما في ذلك استبدال تبويب في مكانه وتنسيقه، في ربط Apple Search Ads بجداول Google.
تصدير Apple Search Ads إلى Looker Studio
لا يملك Hermoso موصّلًا أصليًا لـ Looker Studio، ونفضّل أن نقول ذلك بدلًا من أن نوحي بوجوده. ولا يحتاج إليه: فـ Looker Studio يقرأ جداول Google بموصله المدمج الخاص، فيكون الجدول أعلاه هو الجسر.
- اجعل الوكيل يكتب التقرير في تبويب واحد. مستوى يومي، وصف لكل كلمة مفتاحية في كل يوم، وصف عناوين وعمود تاريخ. اطلب تنسيق عمود التاريخ كتاريخ (
format_sheetيفعل ذلك) حتى يقرأه Looker Studio كتاريخ. - أضف الجدول كمصدر بيانات. في Looker Studio أنشئ مصدر بيانات، واختر Google Sheets، وحدد الجدول والتبويب، واترك "Use first row as headers" مفعّلًا.
- ابنِ التقرير مرة واحدة. الإنفاق حسب اليوم، وتكلفة الاكتساب حسب الكلمة المفتاحية، والتثبيتات حسب الحملة: كل ما كنت ستعيد بناءه في جدول بيانات كل يوم اثنين.
- واصل الإلحاق. كل أسبوع يلحق الوكيل صفوفًا جديدة بالتبويب نفسه، وتلتقطها اللوحة في تحديث البيانات التالي. أبقِ أسماء الأعمدة كما هي بين كل تشغيل وآخر، لأن Looker Studio يربط الحقول بالعناوين.
وتعمل الطريقة نفسها مع Power BI وTableau، فلكل منهما موصل جداول Google خاص به.
تصدير Apple Search Ads إلى JSON
إذا أردت الصفوف الخام بدلًا من جدول، فهناك ثلاث طرق للحصول عليها، وكلها تستخدم الربط نفسه.
واجهة REST. كل أداة في Hermoso قابلة للاستدعاء عبر POST /v1/tools/{name} بمفتاح API تنشئه في التطبيق من تبويب MCP & CLI. جسم الطلب هو معطيات الأداة، وحقل data في الرد هو النتيجة المهيكلة، والصفوف في data.rows:
curl -sX POST https://app.hermoso.ai/v1/tools/apple_ads_report \
-H "Authorization: Bearer hmk_..." -H 'content-type: application/json' \
-d '{"level":"keyword","campaignId":"1234567890","startTime":"2026-09-01","endTime":"2026-09-07","granularity":"DAILY"}' \
| jq '.data.rows' > apple-search-ads.jsonواجهة CLI. npx -y hermoso call apple_ads_report --json '{...}' --structured يطبع النتيجة المهيكلة نفسها بصيغة JSON، جاهزة لإعادة توجيهها إلى ملف أو تمريرها إلى سكربت آخر.
وكيلك. في أي محادثة، اطلب الصفوف بصيغة JSON وستحصل عليها في الرد، مُشكّلة بالطريقة التي طلبتها.
بالنسبة للتقارير الطويلة، يأخذ limit حتى 5,000 صف في الصفحة، وينتقل offset إلى الصفحة التالية؛ ويخبرك hasMore في النتيجة إن كانت هناك صفحة أخرى. قراءة التقرير لا تُنفق أي أرصدة. المرجع الكامل لواجهة البرمجة في وثائق المطوّرين.
الوجهات الأخرى
"مباشرة" يعني أن Hermoso يكتب إليها بنفسه. وكل ما عداه خطوة واحدة تقوم بها أداة تستخدمها أصلًا.
- جداول Google وDocs وDrive وOneDrive: مباشرة.
- Looker Studio وPower BI وTableau: عبر الجدول، ولكلٍّ منها موصل جداول Google الخاص.
- BigQuery: عبر الجدول، أو عبر وكيلك. يستطيع BigQuery الاستعلام عن جدول Google كجدول خارجي. وإذا كان وكيلك يعمل في بيئة فيها عميل BigQuery وبيانات اعتماد مشروعك، فيستطيع إدراج الصفوف التي يعيدها Hermoso مباشرة في جدول.
- Excel: عبر الجدول أو عبر ملف. نزّل الجدول بصيغة .xlsx، أو اجعل الوكيل يترك ملفًا في Google Drive أو OneDrive.
- PostgreSQL أو Redshift أو Snowflake أو أي مستودع بيانات: عبر وكيلك أو واجهة API. يعيد Hermoso بيانات JSON؛ والمسؤول عن بيانات اعتماد قاعدة بياناتك هو ما يكتب فيها. Hermoso لا يحتفظ ببيانات اعتماد المستودع.
أتمتة التصدير الأسبوعي
التعليمات هي الأتمتة. جملة مثل "كل يوم اثنين، اسحب أداء Apple Search Ads للأسبوع الماضي حسب الكلمة المفتاحية لكل الحملات، وألحقه بجدول Apple Ads، وأخبرني بالكلمات التي تغيّرت أكثر في تكلفة الاكتساب" هي مهمة كاملة. شغّلها وفق جدول يملكه عميلك (المهام المجدولة في Claude أو ChatGPT، أو مهمة cron تستدعي CLI أو API الخاصة بـ Hermoso) فيبقى الجدول واللوحات التي تقرؤه محدّثة.
ولأن الربط نفسه يعدّل الحساب أيضًا، يعيش التقرير والإصلاح في مكان واحد: الوكيل الذي يلاحظ أن تكلفة اكتساب كلمة مفتاحية تضاعفت، يستطيع إيقافها أو إضافة سلبية في المحادثة نفسها.
الأسئلة المتكررة
كيف أصدّر البيانات من Apple Search Ads؟
اربط Apple Ads بـ Hermoso مرة واحدة، ثم اطلب من وكيلك التقرير الذي تريده، مثلًا أداء الكلمات المفتاحية للأسبوع الماضي. تسحب الأداة apple_ads_report البيانات من واجهة تقارير Apple البرمجية، ويكتبها الوكيل في جدول Google، أو يعيدها لك JSON، أو الاثنين معًا.
هل يمكنني ربط Apple Search Ads بجداول Google؟
نعم. اربط Apple Ads وGoogle Drive في Hermoso، ثم اطلب من الوكيل وضع التقرير في جدول. يُنشئ الجدول بـ create_sheet، أو يلحق صفوفًا بجدول موجود بـ append_to_sheet، ويمكنه أن يكرر ذلك كل أسبوع.
هل يمكنني تصدير Apple Search Ads إلى Looker Studio؟
نعم، عبر جداول Google. لا يملك Hermoso موصلًا أصليًا لـ Looker Studio. يكتب الوكيل التقرير في جدول، وتضيف أنت ذلك الجدول مرة واحدة كمصدر بيانات Google Sheets في Looker Studio، وتظهر كل إضافة في التحديث التالي للوحة.
كيف أصدّر بيانات Apple Search Ads إلى JSON؟
استدعِ POST /v1/tools/apple_ads_report على واجهة Hermoso API بمفتاح API واقرأ data.rows من الرد، أو شغّل hermoso call apple_ads_report --json '{...}' --structured من CLI. تعيد الطريقتان الصفوف نفسها بصيغة JSON.
هل توجد واجهة برمجية لتقارير Apple Search Ads؟
نعم، وHermoso مبني عليها. تغطي apple_ads_report أداء الحملة ومجموعة الإعلانات والإعلان والكلمة المفتاحية وعبارة البحث، وتتولى الأدوات الأخرى في Apple Ads بناء الحساب وإدارته.
هل يمكنني الحصول على تقارير عبارات البحث في Apple Search Ads؟
نعم. اطلب مستوى عبارة البحث واذكر الحملة. لا تقدم Apple عبارات البحث إلا لكل حملة، وبالمنطقة الزمنية لمؤسستها.
كم صفًا يمكن أن يعيد تقرير واحد؟
حتى 5,000 في الصفحة، مرتبة حسب الإنفاق من الأعلى إلى الأدنى، مع إشارة تخبر الوكيل إن كانت هناك صفحات أخرى. تقرير الكلمات المفتاحية الأسبوعي لمعظم الحسابات يتسع في صفحة واحدة.
هل يشمل ذلك الإعلانات على خرائط Apple؟
نعم. تأتي تقارير حملات العلامات التجارية للأنشطة من الأداة نفسها، مع ضبط نوع الكائن المُروَّج على Apple Maps بدلًا من App Store.
هل أحتاج إلى مطوّر لإعداد هذا؟
لا. اربط Apple Ads مرة واحدة في التطبيق، ثم اطلب من وكيلك بلغة عادية: اسحب الأداء الأسبوع الماضي حسب الكلمة المفتاحية وضعه في جدول. واجهة API وCLI موجودتان إن أردت البرمجة.