התחברות מוטמעת

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

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

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

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

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

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

הטמעת קישור מוטמע

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

1. יצירת פרויקט ב-Google Cloud (או שימוש בפרויקט קיים)
2. יצירת מזהה לקוח OAuth
3. הגדרת מזהה הלקוח של OAuth לשימוש עם embedded Connect
4. (אופציונלי) התאמה אישית של מסך ההסכמה ל-OAuth
5. הוספה של ספריית JavaScript שהוטמעה לחיבור לדף
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, פועלים לפי השלבים הבאים:

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

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

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

כך עושים זאת:

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

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

מסך ההסכמה של OAuth הוא המקום שבו השימושים יעניקו למזהה הלקוח שלכם גישה לנתוני AdSense שלו. זה חלק חשוב באופן הפעולה של 'חיבור מוטמע'. ניתן להתאים אישית את המסך כך שיכלול את שם הפלטפורמה, הלוגו שלך וכו'. יש להיכנס לדף מסך ההסכמה של 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. תתבצע קריאה לפונקציה כשה-API של adsenseEmbeddedConnect יהיה מוכן לשימוש.

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

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

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

src פרמטרים

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

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

הערה: ספריית ה-JavaScript המוטמעת של Connect מגיבה בסטטוס 200 רק אם ה-URI שבו היא נטענת נוספה לרשימת ההיתרים על ידי Google. אחרת, הבקשה תידחה באמצעות קוד 403. לדוגמה, אם אתם מתכוונים להשתמש בספריית JavaScript של 'הטמעת חיבור מוטמע' ב-console.example.com, Google צריכה להוסיף את ה-URI הזה לרשימת ההיתרים כדי שהספרייה תיטען. כדי לפתור את הבעיה בפלטפורמה שלכם, עליכם לפנות למנהל החשבון. באופן דומה, המערכת תחזיר שגיאת 403 אם תנסו להפעיל את embedded Connect מכתובת URL באמצעות פרוטוקול HTTP (יש להשתמש ב-HTTPS).

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

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

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

• חוויית משתמש בניהול Google
• חוויית משתמש בהתאמה אישית

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

חוויית משתמש בניהול Google

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

בקוד הקישור המוטמע יש שני רכיבים. הראשון הוא שדה <div> ריק שמציין את המיקום של 'חיבור מוטמע', שיעבד את ווידג'ט ההרשמה. והשני הוא הקוד שבו נקבעות ההגדרות ומנוהלות הקריאות החוזרות (callback).

אלמנט ה-HTML שבו מעובד הווידג'ט המוטמע של 'חיבור'

יש למקם את ה-HTML הזה בדף שבו רוצים שהווידג'ט של embedded Connect יוצג:

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

קוד החיבור המוטמע

לאחר מכן, מתחת לספריית 'חיבור מוטמע', אבל מעל לרכיב 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': '[e-mail]',

        // 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 לא מופיע בקוד של הקישור המוטמע. הוא מפעיל את תהליך החיבור (חלון קופץ), ואחרי שהמשתמש השלים את התהליך, הוא יפעיל את הקריאה החוזרת (callback) של onConnect.

2. קישור ל-AdSense

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

3. מתבצעת בדיקה של פרטי האתר

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

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

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

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

‫4. זוהו בעיות

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

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

יש לפעול לפי השלבים הבאים אם רוצים לנהל את חוויית המשתמש בעצמכם ולהשתמש בקריאות ל-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.
}