تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يجب أن تتضمّن الطلبات الموجّهة إلى ReachPlanService رمز مطوّر معتمَدًا وبيانات اعتماد OAuth ومعرّف عميل يمكن لبيانات اعتماد OAuth الوصول إليه.
يتناول هذا الدليل تفاصيل المصادقة الخاصة بميزة
ReachPlanService. إذا لم يسبق لك إجراء ذلك،
أكمِل أولاً الخطوات الموضّحة في البدء، ثم ارجع إلى هذه النقطة.
الرمز المميز للمطوّر وبيانات اعتماد OAuth
بالإضافة إلى الإرشادات المقدَّمة من خلال البدء، يُرجى مراعاة النقاط التالية:
يجب إدراج رمز المطوّر المميّز في القائمة المسموح بها للاتصال بـ ReachPlanService، حتى إذا تمت الموافقة عليه مسبقًا لاستخدامه مع خدمات أخرى في Google Ads API. لمزيد من المعلومات، راجِع متطلبات الأهلية.
يجب قبول بنود خدمة Google Ads API من أجل الربط بواجهة Google Ads API.
يحدّد المستخدم الذي يملك رمز التحديث لبروتوكول OAuth معرّفات العملاء التي يمكنك طلب البحث عنها في ReachPlanService.
يُعلم هذا الإجراء عملية الدمج ويتم توضيح المزيد من التفاصيل أدناه.
أرقام التعريف الشخصي IDs للعميل
تعمل معظم الخدمات ضِمن Google Ads API على حسابات وحملات معيّنة على "إعلانات Google". نتيجةً لذلك، تتطلّب معظم الطلبات توفّر رقم تعريف عميل لتحديد الحساب الذي تديره أو تستعلم عنه، بالإضافة إلى بيانات اعتماد OAuth التي لديها إذن بالوصول إلى رقم تعريف العميل هذا. ومع ذلك، فإنّ ReachPlanService
مخصّص لأنشطة تخطيط الفيديو التي قد تحدث قبل معرفة
الرقم التعريفي المحدّد للعميل الذي ستُطلق فيه حملة.
بالنسبة إلى الشركاء الذين ينشئون أدوات للاستخدام الداخلي في مؤسساتهم، ننصحهم باختيار أحد الخيارَين التاليَين:
إذا لم يكن لدى مخطّطيك إذن الوصول إلى حسابات "إعلانات Google" الخاصة بعملائك:
أنشئ بيانات اعتماد OAuth باستخدام مسار التطبيق المثبَّت لمستخدم لديه إذن الوصول إلى الحساب الإداري الخاص برمزك المميز للمطوّر. بعد ذلك، أنشئ أو احصل على حساب على "إعلانات Google" لكل فريق يستخدم أداتك، ثم اربط هذه الحسابات بحسابك الإداري. عند تقديم طلبات إلى
ReachPlanService، يجب تقديم معرّف العميل
المطابق لفريق المستخدم.
إذا كان لدى مخطّطيك إذن الوصول إلى حساب إداري على "إعلانات Google" يدير حسابات عملائك: نفِّذ مسار تطبيق الويب للسماح لتطبيقك باستخدام بيانات اعتماد OAuth الخاصة بمخطّطيك. بعد ذلك، يمكنك إدخال معرّف العميل الذي يتطابق مع عميل خطتك.
بالنسبة إلى الشركاء الذين ينشئون أداة للمستخدمين الخارجيين، ننصح باتّباع طرق مشابهة:
أنشئ بيانات اعتماد OAuth باستخدام مسار التطبيق المثبَّت لمستخدم لديه إذن الوصول إلى حساب مدير الرمز المميز للمطوّر. أنشئ حسابًا على "إعلانات Google" لكل عميل خارجي واربطه بحسابك الإداري. بعد ذلك، اضبط أداتك لتقديم معرّف العميل المقابل لأحد العملاء عند إنشاء الخطط.
امنح المستخدمين إمكانية منح أداتك إذن الوصول إلى حساباتهم
باستخدام مسار تطبيق الويب. بعد أن يمنح المستخدم الإذن، استخدِم CustomerService لتزويده بقائمة بحسابات "إعلانات Google" التي يمكنه الوصول إليها.
والهدف من ذلك هو ضمان أن يواجه المخططون أقل قدر ممكن من الصعوبات عند استخدام ReachPlanService. قبل دمج واجهة برمجة التطبيقات، اختَر أحد الأسلوبَين وفقًا لحالتك وحدِّد بعض أرقام تعريف العملاء لاختبارها. إذا لم تكن متأكدًا، استخدِم الطريقة الأولى المقترَحة لنوع أداتك.
تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-27 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThe ReachPlanService API requires allowlisted access, an approved developer token, OAuth credentials, and a valid customer ID.\u003c/p\u003e\n"],["\u003cp\u003eYour developer token needs to be specifically allowlisted for ReachPlanService, and you must accept the Google Ads API Terms of Service.\u003c/p\u003e\n"],["\u003cp\u003eCustomer ID selection depends on whether planners have access to client accounts or use a manager account, impacting OAuth credential flow.\u003c/p\u003e\n"],["\u003cp\u003ePartners building internal tools can choose between using a manager account with linked team accounts or leveraging planners' existing manager account access.\u003c/p\u003e\n"],["\u003cp\u003ePartners building external tools can use a similar approach, either linking client accounts to a manager account or utilizing the web application flow for direct user account access.\u003c/p\u003e\n"]]],[],null,["# Authentication\n\n| **Important:** This feature is available to allowlisted accounts only. Contact your Google representative if you need access to the feature.\n\n\u003cbr /\u003e\n\nRequests to the [`ReachPlanService`](/google-ads/api/reference/rpc/v21/ReachPlanService) must\nsupply an approved developer token, OAuth credentials, and a customer ID that\nyour OAuth credentials can access.\n\nThis guide covers authentication details specific to\n[`ReachPlanService`](/google-ads/api/reference/rpc/v21/ReachPlanService). If you haven't already,\nfirst complete the steps outlined in [Get\nstarted](/google-ads/api/docs/get-started/introduction), then come back to this point.\n\nDeveloper token and OAuth credentials\n-------------------------------------\n\nIn addition to the guidance presented by [Get\nstarted](/google-ads/api/docs/get-started/introduction), keep the following points in mind:\n\n1. Your developer token must be allowlisted to connect to the [`ReachPlanService`](/google-ads/api/reference/rpc/v21/ReachPlanService), even if it's already approved for use with other Google Ads API services. For more information, see the [eligibility\n requirements](/google-ads/api/docs/reach-forecasting#eligibility).\n2. You must accept the Google Ads API Terms of Service in order to connect to the Google Ads API.\n3. The user who owns your OAuth refresh token determines which customer IDs you can query in the [`ReachPlanService`](/google-ads/api/reference/rpc/v21/ReachPlanService). This informs your integration and is explained in more details below.\n\nCustomer IDs\n------------\n\nMost services within the Google Ads API operate on specific Google Ads accounts and\ncampaigns. As a result, most requests require both a customer ID to identify\nthe account you're managing or querying, and [OAuth\ncredentials](/google-ads/api/docs/oauth/overview) that have permission to access that\ncustomer ID. However, [`ReachPlanService`](/google-ads/api/reference/rpc/v21/ReachPlanService)\nis meant for video planning activities that might occur before you know the\nspecific customer ID where you would run a campaign.\n\nFor partners who build tools for internal use in their organization, we\nrecommend one of the following choices:\n\n1. **If your planners don't have access to your clients' Google Ads accounts** :\n Generate OAuth credentials using the *installed application flow* for a user\n with access to your developer token's manager account. Then create or obtain\n a Google Ads account for each team that uses your tool, and [link them to\n your manager account](//support.google.com/google-ads/answer/7459601). When making requests to\n [`ReachPlanService`](/google-ads/api/reference/rpc/v21/ReachPlanService) provide the customer ID\n corresponding to a user's team.\n\n2. **If your planners have access to a Google Ads manager account that manages\n your clients' accounts** : Implement the *web application flow* to allow your\n app to use your planners' OAuth credentials. Then you can pass in the\n customer ID corresponding to the customer of your plan.\n\nFor partners who build a tool for external users, we recommend similar\napproaches:\n\n1. Generate OAuth credentials using the *installed application flow* for a user\n with access to your developer token's manager account. Create a Google Ads\n account per external client and [link them to your manager\n account](//support.google.com/google-ads/answer/7459601). Then configure your tool to provide a client's\n corresponding customer ID when they're generating plans.\n\n2. Give your users the ability to grant your tool access to their accounts\n by using the *web application flow* . Once a user grants permission, use the\n [`CustomerService`](/google-ads/api/docs/account-management/listing-accounts) to provide\n them with a list of Google Ads accounts they can access.\n\nThe goal is to ensure planners have the lowest possible friction when using the\n[`ReachPlanService`](/google-ads/api/reference/rpc/v21/ReachPlanService). Before you integrate the\nAPI, select one of the two approaches according to your situation and identify\na few customer IDs to test. If in doubt, use the first suggested approach for\nyour tool type."]]
