AdSense for Platforms | Google for Developers

דף זה תורגם על ידי Cloud Translation API.

חיבור מוטמע

הטמעת חיבור מוטמע מפחיתה את החיכוך ומשפרה את משפך ההמרות כשמשתמשים מנסים לחבר את AdSense לפלטפורמה שלכם.

'חיבור מוטמע' הוא ספריית JavaScript קטנה שקובעת מהי נקודת ההתחלה הטובה ביותר עבור משתמש נתון ומנחה אותו בתהליך הרשמה מותאם אישית ל-AdSense, שעוזר לו לבצע את כל השלבים הדרושים כדי להציג מודעות. המערכת מטפלת בתרחישים שונים, כולל בדיקה אם למשתמש יש חשבון AdSense, אם הוא חתם על התנאים וההגבלות של AdSense, אם הוא הוסיף את אתר הפלטפורמה שלכם לחשבון AdSense ואם הסטטוס של האתר הוא 'מוכן'.

הטמעת קישור מוטמע עם אפשרות של חוויית משתמש בניהול Google יכולה גם לטפל בחוויית המשתמש שכרוכה בהצגת הסטטוסים של החשבון והאתר, ולהוביל אותם למקום הנכון ב-AdSense שבו יוכלו לפתור בעיות פוטנציאליות.

כדי לשפר את חוויית המפתחים, הספרייה גם מנפיקה קריאות חוזרות לפלטפורמה, שמכילות את מזהה בעל האתר של המשתמש ב-AdSense, שנדרש כדי להגדיר בצורה נכונה את הצגת המודעות.

התכונה 'חיבור מוטמע' מציעה שתי אפשרויות לחוויית המשתמש:

חוויית משתמש בניהול Google. להשתמש בווידג'ט Embedded Connect, שמנהל את כל חוויית המשתמש. הווידג'ט יעזור למשתמשים בתהליך ההרשמה ויציג למשתמש מידע על הסטטוס של החשבון והאתר שלהם בתוך הווידג'ט. כשמשתמשים באפשרות הזאת, מקבלים קריאה חוזרת (callback) עם מזהה בעל האתר ב-AdSense שמופעל כשהמשתמש מקשר חשבון AdSense בפעם הראשונה.
חוויית משתמש מותאמת אישית. משתמשים בשיטת החיבור adsenseEmbeddedConnect.connect(...) המוטמעת, שמפעילה את תהליך ההרשמה בחלון חדש. בחירה באפשרות הזו מספקת קריאה חוזרת (callback) עם מזהה בעל האתר ב-AdSense ואסימון גישה שניתן להשתמש בו כדי לאחזר מידע נוסף מחשבון AdSense באמצעות AdSense Management API. אם תבחרו באפשרות הזו, אתם צריכים לעצב את חוויית המשתמש בעצמכם.

הטמעה של Embedded Connect

כדי להשתמש ב-Embedded Connect, יהיה עליך לבצע את השלבים הבאים:

יצירת פרויקט ב-Google Cloud (או שימוש בפרויקט קיים)
יצירת מזהה לקוח ב-OAuth
צריך להגדיר את מזהה הלקוח ב-OAuth לשימוש עם 'חיבור מוטמע'
(אופציונלי) התאמה אישית של מסך ההסכמה ל-OAuth
הוספת ספריית JavaScript של 'חיבור מוטמע' לדף
הטמעת הקוד של Embedded Connect

שלב 1: יצירת פרויקט חדש ב-Google Cloud (או שימוש בפרויקט קיים)

אם יש לכם פרויקט קיים ב-Google Cloud, אתם מוזמנים להשתמש בו. אם לא, תוכלו להיעזר במדריך הבא להגדרת פרויקט חדש:

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

שלב 2: יצירת מזהה לקוח ב-OAuth

לפרויקטים ב-Google Cloud יהיה מזהה לקוח OAuth שמוגדר כברירת מחדל, ואפשר להשתמש בו. אפשר למצוא את המידע הזה בממשקי API שירותים > פרטי כניסה.

אם אתם רוצים ליצור מזהה לקוח ייעודי של OAuth, פועלים לפי השלבים הבאים:

מעבר אל APIs & שירותים > פרטי כניסה
לוחצים על '+ יצירת פרטי כניסה'. בחלק העליון של הדף, ובוחרים מזהה לקוח ב-OAuth
סוג האפליקציה יהיה 'אפליקציית אינטרנט'
נותנים שם למזהה הלקוח ולוחצים על 'יצירה'.

שלב 3: מגדירים את מזהה הלקוח ב-OAuth לשימוש עם Embedded Connect

אחרי שתחליטו באיזה מזהה לקוח של OAuth תרצו להשתמש לשילוב של 'חיבור מוטמע', תצטרכו להגדיר אותו.

כך עושים זאת:

בדף פרטי כניסה, לוחצים על סמל העיפרון לצד מזהה הלקוח שרוצים להגדיר.
בקטע מקורות JavaScript מורשים, מוסיפים את מזהי ה-URI שמורשים לשלוח בקשות באמצעות מזהה הלקוח שלכם. בדרך כלל נוספים מזהי URI לשרת הפיתוח ולסביבה המקומית (למשל: https://dev.example.com ו-http://localhost:5000). בנוסף, צריך להוסיף URI עבור סביבת הייצור (למשל, https://example.com)

(אופציונלי) שלב 4: התאמה אישית של מסך ההסכמה ל-OAuth

מסך ההסכמה ל-OAuth הוא המקום שבו המשתמשים יעניקו למזהה הלקוח שלכם גישה לנתונים שלהם ב-AdSense. זהו חלק חיוני באופן הפעולה של Embedded Connect. אפשר להתאים אישית את המסך הזה כך שיכלול את שם הפלטפורמה, הלוגו שלכם וכו'. נכנסים לדף מסך ההסכמה של OAuth כדי להגדיר את ההתאמות האישיות. לוחצים על 'עריכת האפליקציה' בראש הדף ופועלים לפי האשף.

שלב 5: הטמעה של ספריית ה-JavaScript של Embedded Connect

הספרייה הזו מכילה את השיטות השונות המשמשות להפעלת 'חיבור מוטמע', ומספקת לך את הקריאות החוזרות (callback) שנדרשות כדי לאחזר ולשכוח את מזהה בעל האתר של המשתמש. מומלץ להטמיע את הפרמטר הזה בחלק העליון של הדף.

עבור חוויית המשתמש בניהול 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 API מוכן לשימוש.

מאפיינים של תגי סקריפט

שימו לב שבדוגמה שלמעלה הוגדרו מספר מאפיינים בתג הסקריפט. בהמשך מופיע הסבר על כל מאפיין.

src: כתובת ה-URL שממנה נטען Embedded Connect API. כתובת ה-URL עשויה להכיל כמה פרמטרים של שאילתה, המתועדים בהמשך.
async: בקשה מהדפדפן להוריד ולהפעיל את הסקריפט באופן אסינכרוני. לאחר הרצת הסקריפט, הוא יקרא לפונקציה שצוינה באמצעות הפרמטר load.
defer: לאחר ההגדרה, הדפדפן יוריד את קוד ה-JavaScript של 'חיבור מוטמע' במקביל לניתוח הדף, ויפעיל אותו לאחר שניתוח הדף יסתיים.

src פרמטרים

המאפיין src מכיל מספר פרמטרים של שאילתה שנדרשים להפעלת Embedded Connect. בהמשך מוסבר איך משתמשים בכל אחד מהפרמטרים.

load הוא השם של פונקציית JavaScript גלובלית, שתיקרא אחרי שה-API ייטען בשלמותו. אפשר לבחור כל שם לפונקציה הזו.
hl מציין את השפה לשימוש בכל ההתאמה לשוק המקומי, כולל (לדוגמה) הטקסט שמופיע בחלון הקופץ של ההרשמה. זהו פרמטר שאילתה אופציונלי. כאשר הוא לא קיים, או אם השפה לא נתמכת על ידי AdSense, ברירת המחדל של הווידג'ט היא אנגלית (ארה"ב). אילו שפות נתמכות ב-AdSense? ערך הפרמטר hl חייב להיות תואם לBCP 47, לדוגמה, למשתמשים באנגלית בריטית, המחרוזת תהיה en-GB.
headless=true מציין שייעשה שימוש ב-מוטמע ב-Connect עם האפשרות 'חוויית משתמש בהתאמה אישית' במקום UX שמנוהל על ידי Google.

עכשיו, אחרי שבחרתם בין UX בניהול Google לבין UX בהתאמה אישית, המשיכו לראות את דוגמאות הקוד של כל אחת מהגישות הבאות.

שלב 6: מטמיעים את הקוד של Embedded Connect

כפי שצוין למעלה, יש שתי אפשרויות לחוויית המשתמש:

צריך לבחור את אפשרות ההטמעה שהכי מתאימה לצורכי הפלטפורמה שלכם.

UX בניהול Google

יש לבצע את השלבים הבאים כדי ש-Google תעבד את הווידג'ט שמפעיל את תהליך ההרשמה ויציג למשתמש מידע רלוונטי לגבי מצב החשבון והאתר.

מצב ברירת מחדל של חיבור מוטמע

יש שני רכיבים בקוד של Embedded Connect. הערך הראשון הוא <div> ריק שמציין איפה התכונה 'חיבור מוטמע' צריכה לעבד את ווידג'ט ההרשמה. השני הוא הקוד שבו נקבעות ההגדרות ומנוהלות הקריאות החוזרות.

רכיב ה-HTML שבו מתבצע הרינדור של הווידג'ט Embedded Connect

יש להוסיף את ה-HTML הזה לדף שבו רוצים שהווידג'ט של Embedded Connect יבצע עיבוד:

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

הקוד של Embedded 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
        },
    });
};

צילומי מסך

לווידג'ט Embedded Connect יש ארבעה מצבים עיקריים:

(ברירת מחדל) קישור ל-AdSense
התחברות ל-AdSense
בדיקת פרטי האתר
זוהו בעיות

1. (ברירת מחדל) קישור ל-AdSense

זהו מצב ברירת המחדל, שמוצג למשתמשים כשהשדה publisherId בקוד של החיבור המוטמע לא נמצא. מתחיל תהליך החיבור (חלון קופץ) ובסיום התהליך על ידי המשתמש, הוא מפעיל את הקריאה החוזרת של onConnect.

מצב ברירת מחדל של חיבור מוטמע

2. התחברות ל-AdSense

המצב הזה מוצג למשתמשים כשהם מתחילים את תהליך החיבור (והחלון הקופץ מופיע). עם סגירת החלון הקופץ או השלמת התהליך, המצב הזה ישתנה לאחד מהמצבים האחרים.

מוטמע – התחברות ל-AdSense

3. בדיקת פרטי האתר

לאחר שאתר חדש נשלח ל-AdSense, יתבצע תהליך בדיקה. לא ניתן להציג מודעות בפרק הזמן הזה.

חיבור מוטמע – בדיקת פרטי האתר

מרכיב קריטי בבדיקה הוא בדיקת בעלות. אפשר להעביר אותה בכמה דרכים, למשל:

מזהה בעל האתר של חשבון הצאצא מופיע בקובץ ה-ads.txt
מזהה בעל האתר של חשבון הצאצא מופיע בתג מודעה באתר של המשתמש
המטא תג google-adsense-child-account נמצא באתר של המשתמש. לקבלת התוצאות הטובות ביותר, מומלץ לוודא שהוא מופיע בדף הבית של האתר של המשתמש.

הגישה הטובה ביותר תלויה במבנה של כתובת ה-URL ובגורמים נוספים. כדאי להתייעץ עם מנהל החשבון כדי להחליט מהי הגישה המתאימה ביותר לפלטפורמה שלכם.

4. זוהו בעיות

אם יש בעיות שצריך לפתור בחשבון או באתר של המשתמש, המצב הזה יוצג למשתמשים.

Embedded Connect – זוהו בעיות

חוויית משתמש מותאמת אישית

אפשר לבצע את השלבים הבאים אם אתם רוצים לנהל את חוויית המשתמש בעצמכם, ולהשתמש בקריאות ל-API כדי להפעיל את שיטת ההרשמה באופן ידני.

ספריית JavaScript המוטמעת

כדי להשתמש באפשרות של חוויית משתמש בהתאמה אישית, יש להגדיר את הפרמטר headless=true במאפיין src. לדוגמה:

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

הוספת לחצני התחברות וניתוק

כשממשק ה-API של 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.
}