الربط المضمّن

يقلل الربط المضمّن المعوقات من الصعوبات ويحسِّن مسار الإحالة الناجحة عندما يحاول المستخدمون ربط AdSense بالمنصّة التي تتعامل معها.

الربط المضمّن هو مكتبة JavaScript صغيرة تحدّد أفضل نقطة انطلاق لمستخدم معيّن وترشده خلال عملية اشتراك مخصّصة في AdSense، والذي يساعده في تنفيذ جميع الخطوات المطلوبة ليصبح قادرًا على عرض الإعلانات. وتعالج السيناريوهات التي تشمل تحديد ما إذا كان المستخدم يملك حسابًا على AdSense، وما إذا كان قد وقّع أحكام وشروط AdSense، وما إذا كان قد أضاف الموقع الإلكتروني للمنصّة إلى حسابه على AdSense، وما إذا كانت حالة الموقع "جاهز".

يمكن أيضًا لمنصة Connected Connect باستخدام خيار تجربة المستخدم التي تديرها Google معالجة تجربة المستخدم المرتبطة بعرض حالات الحساب والموقع الإلكتروني للمستخدم وتوجيهه إلى المكان الصحيح في AdSense لحل أي مشاكل محتملة.

للمساعدة في تقديم تجربة للمطوّرين، يتم أيضًا إرسال طلبات معاودة الاتصال إلى منصتك تحتوي على الرقم التعريفي للناشر في AdSense الخاص بالمستخدم، وهو أمر ضروري لإعداد عرض الإعلانات بشكل صحيح.

يقدم الربط المضمّن خيارين للشكل الذي تبدو عليه تجربة المستخدم:

  • تجربة المستخدم التي تديرها Google: استخدام التطبيق المصغَّر لـ Include Connect، الذي يدير جميع تجربة المستخدم. ستساعد الأداة المستخدمين خلال عملية الاشتراك وعرض معلومات للمستخدمين حول حساباتهم وحالة موقعهم الإلكتروني داخل الأداة. يوفّر هذا الخيار معاودة الاتصال بالرقم التعريفي للناشر في AdSense الذي يتم تشغيله عندما يربط المستخدم حساب AdSense لأول مرة.
  • تجربة المستخدم المخصّصة: استخدِم طريقة الربط المضمّن adsenseEmbeddedConnect.connect(...) التي تؤدي إلى بدء عملية الاشتراك في نافذة جديدة. يوفّر هذا الخيار معاودة الاتصال بالرقم التعريفي للناشر في AdSense ورمز دخول يمكن استخدامه لجلب معلومات إضافية من حساب AdSense باستخدام AdSense Management API. يتطلب منك هذا الخيار تصميم تجربة المستخدم بنفسك.

تنفيذ الربط المضمّن

لاستخدام Connected Connect، ستحتاج إلى اتباع الخطوات التالية:

  1. إنشاء مشروع في Google Cloud (أو استخدام مشروع حالي)
  2. إنشاء معرِّف عميل OAuth
  3. إعداد معرِّف عميل OAuth لاستخدامه مع Embed Connect
  4. (اختياري) تخصيص شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth
  5. إضافة مكتبة JavaScript Connect Connect إلى الصفحة
  6. تنفيذ رمز Embed Connect

الخطوة 1: إنشاء مشروع جديد على Google Cloud (أو استخدام مشروع حالي)

إذا كان لديك مشروع حالي على Google Cloud، يمكنك استخدامه. بخلاف ذلك، اتبع الدليل أدناه حول إعداد مشروع جديد:

https://cloud.google.com/resource-manager/docs/creating-managing-projects

الخطوة 2: إنشاء معرِّف عميل OAuth

ستتضمّن مشاريع Google Cloud معرّف عميل OAuth تلقائي يمكنك استخدامه. يمكنك العثور عليه من خلال الانتقال إلى واجهات برمجة التطبيقات الخدمات > بيانات الاعتماد:

إذا أردت إنشاء معرِّف عميل OAuth مخصّص، يُرجى اتّباع الخطوات التالية:

الخطوة 3: ضبط معرِّف عميل OAuth لاستخدامه مع الربط المضمَّن

بعد تحديد معرّف عميل OAuth الذي تريد استخدامه لدمج الربط المضمّن، ستحتاج إلى إعداده.

اتبع الخطوات التالية:

  • من صفحة بيانات الاعتماد، انقر على رمز القلم الرصاص لمعرِّف العميل الذي تريد ضبطه.
  • في قسم مصادر JavaScript المعتمَدة، أضِف معرّفات الموارد المنتظمة (URI) المسموح لها بإصدار الطلبات باستخدام معرِّف العميل. تتم عادةً إضافة معرّفات الموارد المنتظمة (URI) لخادم التطوير والبيئة المحلية (مثل https://dev.example.com وhttp://localhost:5000). عليك أيضًا إضافة عنوان URI لبيئة الإنتاج (مثل https://example.com).

شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth هي المكان الذي سيمنح خلاله معرِّف العميل إمكانية الوصول إلى بيانات AdSense. يعد هذا جزءًا أساسيًا من كيفية عمل Embed Connect. ويمكنك تخصيص هذه الشاشة لتتضمّن اسم المنصّة وشعارك وما إلى ذلك. انتقِل إلى صفحة شاشة موافقة OAuth لضبط عمليات التخصيص. انقر على "تعديل التطبيق" في أعلى الصفحة واتبع المعالج.

الخطوة 5: تنفيذ مكتبة JavaScript Connect Connect

تحتوي هذه المكتبة على الطرق المختلفة المستخدمة لبدء الاتصال المُضمَّن وتزويدك بعمليات الاستدعاء اللازمة لاسترداد ونسيان الرقم التعريفي للناشر الخاص بالمستخدم. يتم تنفيذ هذا الإجراء باتجاه رأس الصفحة.

بالنسبة إلى تجربة المستخدم التي تديرها Google:

<script src="https://www.google.com/adsense/js/embedded-connect.js?load=initEmbeddedConnect&hl={language}" async defer></script>

بالنسبة إلى تجربة المستخدم المخصّصة:

<script src="https://www.google.com/adsense/js/embedded-connect.js?load=initEmbeddedConnect&hl={language}&headless=true" async defer></script>

تأكَّد من تقديم عملية تنفيذ لاسم دالة JavaScript الذي تم تمريره. في المعلمة load. سيتم استدعاء الدالة عندما واجهة برمجة تطبيقات adsenseEmbeddedConnect جاهزة للاستخدام.

سمات علامة النص البرمجي

لاحِظ في المثال أعلاه أنّه تم ضبط عدة سمات على علامة النص البرمجي. في ما يلي شرح لكل سمة.

  • src: عنوان URL الذي يتم منه تحميل واجهة برمجة التطبيقات inline Connect API قد يحتوي عنوان URL على معلَمات طلب بحث متعددة، موثّقة أدناه.
  • async: يطلب من المتصفّح تنزيل النص البرمجي وتنفيذه بشكل غير متزامن. عند تنفيذ النص البرمجي، سيتم استدعاء الدالة المحددة باستخدام المعلمة load.
  • defer: عند ضبط هذه السياسة، سينزِّل المتصفِّح JavaScript للربط المُضمَّن بالتوازي مع تحليل الصفحة، وسينفِّذه بعد انتهاء تحليل الصفحة.

src مَعلمات

تحتوي السمة src على العديد من مَعلمات طلب البحث اللازمة لبدء الربط المضمَّن. يمكنك الاطّلاع أدناه على استخدام كل مَعلمة.

  • load هو اسم دالة JavaScript عمومية سيتم استدعاؤها عند تحميل واجهة برمجة التطبيقات بالكامل. يمكنك اختيار أي اسم لهذه الدالة.
  • يحدّد hl اللغة المراد استخدامها في جميع عمليات الأقلمة، بما في ذلك (على سبيل المثال) النص في النافذة المنبثقة للاشتراك. هي مَعلمة طلب بحث اختيارية، وفي حال عدم توفّرها أو إذا كانت اللغة غير متاحة في AdSense، سيتم ضبط الأداة تلقائيًا على اللغة الإنجليزية (الولايات المتحدة). اطّلع على اللغات التي يدعمها AdSense. يجب أن تتّبع قيمة المعلَمة hl BCP 47. على سبيل المثال، لمستخدمي اللغة الإنجليزية البريطانية، ستكون السلسلة en-GB.
  • تشير القيمة headless=true إلى أنّه سيتم استخدام الربط المضمَّن مع خيار "تجربة المستخدم المخصّصة" بدلاً من "تجربة المستخدم" التي تديرها Google.

الآن بعد أن اخترت بين تجربة المستخدم التي تديرها Google وتجربة المستخدم المخصصة، تابع لرؤية أمثلة التعليمات البرمجية لكل نهج أدناه.

الخطوة 6: تنفيذ رمز Embed Connect

وكما ذكرنا أعلاه، يتوفّر خياران لشكل تجربة المستخدم:

حدِّد خيار التنفيذ الأنسب لاحتياجات منصّتك.

تجربة المستخدم المُدارة من Google

اتّبِع الخطوات التالية لتتمكّن Google من عرض الأداة التي تؤدّي إلى بدء عملية الاشتراك وعرض معلومات ذات صلة للمستخدم حول حالة حسابه وموقعه الإلكتروني.

الحالة التلقائية لـ Include Connect

هناك مكونان لرمز Embed Connect. العنصر الأول هو <div> فارغ يحدّد المكان الذي يجب أن يعرض فيه Embed Connect أداة الاشتراك. والثاني هو الرمز الذي يتم فيه ضبط عمليات الضبط وإدارة عمليات معاودة الاتصال.

عنصر HTML حيث يتم عرض التطبيق المصغَّر الخاص بالربط المُضمَّن

ضع كود HTML هذا في الصفحة التي تريد أن يتم عرض أداة الربط المضمَّن عليها:

<div id="adsenseEmbeddedConnect"></div>

رمز Connected Connect

بعد ذلك، ضع رمز الإعداد أسفل مكتبة Connected Connect ولكن أعلى عنصر div:

function initEmbeddedConnect() {
    adsenseEmbeddedConnect.init({
        // <div> to show the Embedded Connect widget in
        'divId': 'adsenseEmbeddedConnect',

        // OAuth client ID from step 2
        'clientId': 'xxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com',

        // Access token from the Google Identity APIs, see
        // https://developers.google.com/identity/oauth2/web/guides/use-token-model
        // Use the following scope when requesting the access token:
        // https://www.googleapis.com/auth/adsense.readonly
        'accessToken': 'xxxxxxxxxxxxxxxxxxxxxxx',

        // Login hint, an optional parameter which suppresses the account
        // chooser and either pre-fills the email box on the sign-in form,
        // or selects the proper session (if the user is using multiple
        // sign-in)
        'loginHint': 'user@example.com',

        // Child site (which is added to AdSense as part of the Embedded Connect flow)
        // Consult with your account manager to ensure this value is set correctly for your platform
        'siteUrl': 'site.example.com',

        // Optional parameter, the publisher ID of the user.
        // When set, the Embedded Connect widget will display the state of the user's AdSense account.
        // When unset, the Embedded Connect widget will show the default state which triggers the connection flow.
        'publisherId': "pub-0000000000000000",

        'onConnect': function(pid) {
          // Your custom code to send the publisher ID (pid) to your server for it to be saved.
          // The onConnect function is called when the user has completed all the onboarding steps
        },
        'onDisconnect': function() {
          // Your custom code to forget the publisher ID.
          // This onDisconnect function is called when the user has clicked the "Disconnect" button in the Embedded Connect widget
        },
    });
};
لقطات الشاشة

يحتوي أداة الربط المضمّن على أربع حالات رئيسية:

  1. (تلقائي) الربط بحساب AdSense
  2. جارٍ الربط بخدمة AdSense
  3. جارٍ مراجعة معلومات الموقع الإلكتروني
  4. تمّ رصد بعض المشاكل.
1. (تلقائي) الربط بحساب AdSense

هذه هي الحالة التلقائية التي يتم عرضها للمستخدمين عندما لا يكون الحقل publisherId في رمز الربط المضمَّن. ويؤدي ذلك إلى بدء تدفق الاتصال (منبثق) وعند إكمال المستخدم لمسار الاتصال بنجاح، سيؤدي إلى بدء معاودة الاتصال بـ "onConnect".

الحالة التلقائية لـ Include Connect

2. جارٍ الربط بخدمة AdSense

وتظهر هذه الحالة للمستخدمين عندما يبدأون تدفق الاتصال (وتكون النافذة المنبثقة موجودة). عند إغلاق النافذة المنبثقة أو اكتمال التدفق، يتم تغيير هذه الحالة إلى إحدى الحالات الأخرى.

الربط المضمّن - الربط بحساب AdSense

3- جارٍ مراجعة معلومات الموقع الإلكتروني

بعد إرسال موقع جديد إلى AdSense، سيتم إجراء عملية مراجعة. ولا يمكن عرض الإعلانات خلال هذه الفترة.

الربط المضمّن - مراجعة معلومات الموقع الإلكتروني

الربط المضمّن - مراجعة معلومات الموقع الإلكتروني مع فتح القائمة

تشكّل عملية التحقّق من الملكية جزءًا أساسيًا من المراجعة، ويمكن اجتيازها بعدّة طُرق، بما في ذلك:

  • الرقم التعريفي للناشر الخاص بالحساب الفرعي مدرَج في ملف ads.txt
  • الرقم التعريفي لناشر الحساب الفرعي متوفّر في علامة إعلان على الموقع الإلكتروني للمستخدم.
  • العلامة الوصفية google-adsense-child-account ضمن الموقع الإلكتروني للمستخدم. ولتحقيق أفضل النتائج، تأكَّد من توفُّره على الصفحة الرئيسية لموقع المستخدم.

وتعتمد أفضل طريقة على بنية عنوان URL وعلى بعض العوامل الأخرى. يُرجى استشارة مدير حسابك لمعرفة أفضل نهج يناسب منصتك.

4. تمّ رصد بعض المشاكل.

في حال وجود أي مشاكل في حساب المستخدم أو موقعه الإلكتروني يجب حلّها، سيتم عرض هذه الحالة للمستخدمين.

الربط المضمّن - تم رصد مشاكل

الربط المضمّن - تم رصد مشاكل أثناء فتح القائمة

تجربة المستخدم المخصّصة

اتّبِع الخطوات التالية إذا كنت تريد إدارة تجربة المستخدم بنفسك، واستخدِم طلبات البيانات من واجهة برمجة التطبيقات لتشغيل طريقة الاشتراك يدويًا.

مكتبة JavaScript للربط المضمّن

لاستخدام خيار "تجربة المستخدم المخصّصة"، يجب ضبط المَعلمة headless=true في السمة src. على سبيل المثال:

<script src="https://www.google.com/adsense/js/embedded-connect.js?load=initEmbeddedConnect&hl={language}&headless=true" async defer></script>

توفير زرَّي الاتصال وقطع الاتصال

عندما تصبح واجهة برمجة التطبيقات adsenseEmbeddedConnect جاهزة للاستخدام (كما تم التحقّق منه من خلال واجهة برمجة التطبيقات) دالة JavaScript التي تم تمريرها إلى المعلمة load)، يجب تنفيذ حول ربط حسابك بحساب AdSense وإلغاء ربطه على سبيل المثال، من خلال توفير اثنين الأزرار:

<button onclick="connectAdSense()">Connect to AdSense</button>
<button onclick="disconnectAdSense()">Disconnect account</button>

استنادًا إلى ما إذا كان لديك رقم تعريفي للناشر محفوظ من المستخدم أم لا، يمكنك اختيار الزر الذي تريد عرضه.

رمز الاتصال

function connectAdSense(){
    adsenseEmbeddedConnect.connect({
        // OAuth client ID
        'clientId': 'xxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com',

        // Access token from the Google Identity APIs, see
        // https://developers.google.com/identity/oauth2/web/guides/use-token-model
        // Use the following scope when requesting the access token:
        // https://www.googleapis.com/auth/adsense.readonly
        'accessToken': 'xxxxxxxxxxxxxxxxxxxxxxx',

        // Child site (which is added to AdSense as part of the Embedded Connect flow)
        // Consult with your account manager to ensure this value is set correctly for your platform
        'siteUrl': 'site.example.com',

        'onConnect': function(response) {
            // Your custom code to send the publisher ID (response[publisherId]) to your server for it to be saved.
            // The onConnect function is called when the user has completed all the onboarding steps
            // Note that you'll additionally receive an OAuth2 access token (response[token]) which can be used with the AdSense Management API to perform other operations
        },
        'onCancel': function() {
            // This callback is called if the user closes the popup window without completing the sign-up flow
        }
    });
}

رمز قطع الاتصال

function disconnectAdSense(){
    // Your custom code to forget the publisherId from your server.
}