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

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

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

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

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

يتيح لك "الربط المُضمَّن" خياران لتجربة المستخدم:

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

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

لاستخدام ميزة "الربط المُضمّن"، عليك اتّباع الخطوات التالية:

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

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

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

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

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

تتضمّن مشاريع Google Cloud معرِّف عميل OAuth تلقائيًا يمكنك استخدامه. يمكنك العثور عليه من خلال الانتقال إلى APIs & Services (واجهات برمجة التطبيقات والخدمات) > Credentials (بيانات الاعتماد).

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

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

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

يُرجى اتّباع الخطوات التالية:

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

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

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

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

بالنسبة إلى تجربة المستخدم التي تديرها 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: تنفيذ رمز الربط المضمَّن

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

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

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

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

الحالة التلقائية للربط المضمّن

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

عنصر HTML الذي تظهر فيه أداة "الربط المُضمَّنة"

ضع HTML على الصفحة التي تريد أن تعرضها أداة "الربط المُضمَّنة":

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

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

بعد ذلك، أسفل مكتبة inline 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.

الحالة التلقائية للربط المضمّن

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

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

الربط المضمَّن: الربط بخدمة AdSense

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

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

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

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

يشكّل إثبات الملكية أحد العناصر المهمة في المراجعة، ويمكن تمريره بعدّة طرق، بما في ذلك:

  • أن يكون الرقم التعريفي للناشر في الحساب الفرعي متوفرًا في ملف 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.
}