ב-3 במאי 2023 נוציא משימוש את Transactions API, לפני ההוצאה משימוש של Conversations Actions ב-13 ביוני 2023. כאן תוכלו לקרוא מידע נוסף על ההוצאה משימוש של 'פעולות שיחה'.

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

יצירת עסקאות דיגיטליות לצריכה

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

מונחים עיקריים: מוצר דיגיטלי מתכלה הוא יחידה לניהול מלאי (מק"ט) המשתמש יכול להשתמש ולרכוש יותר מפעם אחת, למשל כמות של כסף וירטואלי במשחק למשחק Android. מוצר דיגיטלי זה שונה ממוצר שאינו מתכלה. מוצר דיגיטלי שהמשתמש יכול לרכוש פעם אחת בלבד.

למידע נוסף על מוצרי צריכה חד-פעמיים, אפשר לעיין במאמר בנושא Android התיעוד מופעל תכונות חד-פעמיות ספציפיות למוצר.

תהליך העסקה

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

מגדירים לקוח API לרכישות דיגיטליות: הפעולה משתמשת רכישות API לתקשורת עם המלאי שלך ב-Google Play וביצוע עסקאות. לפני שהפעולה מבצעת פעולה אחרת, היא יוצרת לקוח JWT עם מפתח שירות לתקשורת עם ממשק ה-API של רכישות דיגיטליות.
איסוף מידע: הפעולה אוספת מידע בסיסי על ואת המלאי שלכם ב-Google Play כהכנה לעסקה.
1. לאמת את הדרישות לעסקאות: הפעולה מתבססת על הדרישות לעסקאות בתחילת תהליך הרכישה, ולוודא שהמשתמש יכול לבצע עסקאות.
2. איסוף מלאי זמין: הפעולה בודקת את חשבון Google Play שלכם של מלאי המוצרים שלו ומזהה אילו פריטים זמינים כרגע לרכישה.
יוצרים את ההזמנה: הפעולה מציגה את המוצרים הדיגיטליים הזמינים כדי למשתמשים, כדי שהם יוכלו לבחור אחד לרכישה.
השלמת הרכישה: הפעולה משתמשת ב-API של רכישות דיגיטליות כדי ליזום רכישה באמצעות הבחירה של המשתמש מחנות Google Play.
טיפול בתוצאה: הפעולה מקבלת קוד סטטוס של עסקה ומיידע את המשתמש שהרכישה הצליחה (או לוקחת שלבים נוספים).
מגדירים את הרכישה כרכישה חוזרת: הפעולה משתמשת ברכישות הדיגיטליות API ל-"consume" הפריט שנרכש, והוא יהיה זמין לרכישה שוב על ידי המשתמש הזה.

הנחיות בנושא הגבלות ובדיקה

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

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

אוסטרליה
ברזיל
קנדה
אינדונזיה
יפן
מקסיקו
רוסיה
סינגפור
תאילנד
טורקיה
בריטניה
ארצות הברית

דרישות מוקדמות

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

א' חשבון פיתוח וגם חשבון של מוכר/ת ב-Google Play, כדי לנהל את המוצרים הדיגיטליים שלכם מסוף Google Play.
דומיין אינטרנט מאומת ב-Google Search Console. הדומיין הזה לא צריך להיות משויך לאתר שפורסם באופן ציבורי, אנחנו צריכים רק להפנות לדומיין האינטרנט שלך.
אפליקציה ל-Android עם com.android.vending.BILLING הרשאה ב-Google Play Console. המוצרים הדיגיטליים שלך יהיו 'רכישות מתוך האפליקציה' שמשויכים לאפליקציה הזו ב-Google Play Console.

צריך גם ליצור גרסה ב-Play Console באמצעות האפליקציה הזו, אבל אם אם אינך רוצה שהגרסה תהיה גלויה לכולם, אפשר ליצור גרסת אלפא סגורה גרסה.

אם עדיין אין לך אפליקציה ל-Android, פועלים לפי ההוראות שיוך הוראות לאפליקציה ל-Android.
מוצר מנוהל אחד או יותר ב Google Play Console, שהם המוצרים הדיגיטליים שאתם מוכרים יחד עם הפעולה. שימו לב: לא ניתן ליצור מוצרים מנוהלים ב-Play Console לפני שמגדירים את דרישה מוקדמת לאפליקציה ל-Android.

אם עדיין אין לכם מוצרים מנוהלים, פועלים לפי ההוראות יוצרים את ההוראות ליצירת מוצרים דיגיטליים.

שיוך אפליקציה ל-Android

אם אין לך כרגע אפליקציה ל-Android עם הרשאת החיוב ב ב-Google Play Console, פועלים לפי השלבים הבאים:

ב-Android Studio או סביבת הפיתוח המשולבת (IDE) של Android לבחירתכם. אתם יכולים ליצור פרויקט חדש. בחירת אפשרויות ב: את ההנחיות להגדרת הפרויקט כדי ליצור אפליקציה בסיסית מאוד.
נותנים לפרויקט שם חבילה, למשל com.mycompany.myapp. אין להשאיר את השם הזה כברירת מחדל, מאחר שלא ניתן להעלות חבילות כוללים את com.example ב-Play Console.
פותחים את הקובץ AndroidManifest.xml של האפליקציה.

מוסיפים את שורת הקוד הבאה בתוך הרכיב manifest:

<uses-permission android:name="com.android.vending.BILLING" />

קובץ AndroidManifest.xml צריך להיראות כמו בלוק הקוד הבא:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.mycompany.myapp">
    <uses-permission android:name="com.android.vending.BILLING" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme" />
</manifest>

בונים את האפליקציה כ-APK חתום. ב-Android Studio, מבצעים את השלבים הבאים:
1. נכנסים אל Build (יצירת חבילה / APK חתומה) ויצירת חבילה חתומה / APK.
2. לוחצים על הבא.
3. בקטע Key store path (נתיב מאגר מפתחות), לוחצים על Create new (יצירת חדש).
4. ממלאים כל אחד מהשדות ולוחצים על אישור. חשוב לרשום את חנות המפתחות שלך סיסמה וסיסמאות מפתחות, ושמרו אותן במקום בטוח, תשתמש בהם בהמשך.
5. לוחצים על הבא.
6. בוחרים גרסה.
7. בוחרים באפשרות V1 (JAR Signature).
8. לוחצים על סיום.
9. אחרי כמה שניות, מערכת Android Studio יוצרת קובץ app-release.apk. איתור הקובץ לשימוש במועד מאוחר יותר.
ב Google Play Console, יוצרים אפליקציה חדשה.
עוברים אל גרסאות של אפליקציות.
בקטע מסלולים סגורים, עוברים אל ניהול ואז אלפא.
לוחצים על הלחצן Create Release (יצירת גרסה).
בקטע מתן הרשאה ל-Google לנהל את מפתח החתימה שלך ולהגן עליו, מזינים את החתימה שלכם מידע חשוב.
מעלים את קובץ ה-APK.
לוחצים על שמירה.

יצירת מוצרים דיגיטליים

אם אין לך כרגע מוצרים דיגיטליים ב-Play Console, צריך לפעול לפי השלבים הבאים שלבים:

ב Google Play Console, עוברים אל מוצרים מתוך האפליקציה ואז אל מוצרים מנוהלים. אם מוצגת אזהרה, פועלים לפי ההוראות הקודמות כדי ליצור אפליקציה ל-Android או לוחצים על הקישור כדי ליצור פרופיל מוכר.
לוחצים על יצירת מוצר מנוהל.
ממלאים את השדות של המוצר הדיגיטלי. שימו לב למזהה המוצר כך תפנו למוצר הזה מהפעולה.
לוחצים על שמירה.
חוזרים על שלבים 2 עד 4 לכל מוצר שרוצים למכור.

דוגמאות למוצרים מתכלים ב-Google Play Console.

מכינים את פרויקט הפעולות

כשהמוצרים הדיגיטליים שלך מוגדרים ב-Google Play Console, עליך להפעיל עסקאות דיגיטליות ולשייך את פרויקט הפעולות לאפליקציית Play.

הגדרה

כדי להפעיל עסקאות של מוצרים דיגיטליים בפרויקט Actions (פעולות), יש לפעול לפי השלבים הבאים שלבים:

במסוף Actions, פותחים את הפרויקט או יוצרים פרויקט חדש.
נכנסים לקטע פריסה ואז אל פרטי ספרייה.
בקטע מידע נוסף ועסקאות, מסמנים את התיבה כן. בקטע האם הפעולות משתמשות ב-Digital Purchase API כדי לבצע עסקאות של מוצרים דיגיטליים.
לוחצים על שמירה.

יצירת מפתח API למוצרים דיגיטליים

כדי לשלוח בקשות ל-Digital Products (API) של מוצרים דיגיטליים, צריך להוריד שירות JSON מפתח החשבון שמשויך לפרויקט ב-Actions Console.

כדי לאחזר את המפתח של חשבון השירות, פועלים לפי השלבים הבאים:

במסוף הפעולות, לוחצים על סמל שלוש הנקודות בפינה השמאלית העליונה. ואז על הגדרות הפרויקט.
מאתרים את Project ID של הפעולה.
לחיצה על הקישור הזה תחליף את "<project_id>" עם מזהה הפרויקט שלכם: https://console.developers.google.com/apis/credentials?project=project_id
בתפריט הניווט הראשי, עוברים אל Credentials (פרטי כניסה).
בדף שמופיע, לוחצים על Create credentials ואז על Service מפתח החשבון.
עוברים אל Service Account ולוחצים על New Service Account.
נותנים לחשבון השירות שם כמו Digitaltransactions.
לוחצים על יצירה.
מגדירים את Role בתור Project > בעלים.
לוחצים על המשך.
לוחצים על Create Key.
בוחרים את סוג המפתח JSON.
לוחצים על Create key ומורידים את המפתח של חשבון השירות בפורמט JSON.

כדאי לשמור את המפתח של חשבון השירות במקום בטוח. המפתח הזה ישמש אותך ליצירת לקוח ל-API של רכישות דיגיטליות.

קישור למלאי שלכם ב-Play

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

כדי לקשר את הדומיין והאפליקציה של האתר ב-Play Console לפרויקט Actions, פועלים לפי ההוראות הבאות: את השלבים הבאים:

במסוף Actions, נכנסים אל Deploy ואז אל Brand verification.
אם עדיין לא קישרתם אף נכס, קודם צריך לקשר אתר:
1. לחץ על הלחצן של נכס האינטרנט (</>).
2. מזינים את כתובת ה-URL של דומיין האינטרנט ולוחצים על קישור.
Google תשלח אימייל עם הוראות נוספות לאדם לעבור אימות עבור דומיין האינטרנט הזה Google Search Console. אחרי שנמען האימייל יבצע את השלבים האלה, האתר אמור יופיעו בקטע אימות המותג.
לאחר שיש לך לפחות אתר מקושר אחד, מבצעים את השלבים הבאים כדי: חיבור אפליקציית Android:
1. במסוף Actions, נכנסים אל Deploy ואז אל Brand verification.
2. לחץ על חבר אפליקציה.
3. בדף שמופיע, פועלים לפי ההוראות לאימות כתובת האינטרנט הדומיין ב-Play Console. בוחרים את אפליקציית Play שמכילה את מוצרים דיגיטליים ולהזין את כתובת האתר של דומיין האינטרנט בדיוק כפי שהיא מוצגת אימות המותג.
  
  שוב, Google שולחת הודעת אימות לבעלים המאומת של הדומיין. לאחר שאפליקציית Play תאשר את האימות, האפליקציה שלך ב-Play יופיעו בקטע אימות המותג.
  
  הערה: דומיין האתר יופיע ב-Play Console לפני שהוא יופיע במסוף Actions. ייתכן שיחלפו כמה ימים עד שמסוף Actions כדי לעדכן.
4. מפעילים את האפשרות גישה לרכישות ב-Play.

תמונה שמראה אתר ואפליקציות שמקושרים לפרויקט Actions.

בניית תהליך הרכישה

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

1. הגדרה של לקוח API לרכישות דיגיטליות

בשיחה עם ה-webhook של מילוי הבקשה, צריך ליצור לקוח JWT עם השירות את מפתח JSON של החשבון, היקף הרשאות אחד (https://www.googleapis.com/auth/actions.purchases.digital).

הקוד הבא של Node.js יוצר לקוח JWT ל-API לרכישות דיגיטליות:

  const serviceAccount = {'my-file.json'};
  const request = require('request');
  const {google} = require('googleapis');

  const jwtClient = new google.auth.JWT(
    serviceAccount.client_email, null, serviceAccount.private_key,
    ['https://www.googleapis.com/auth/actions.purchases.digital'],
    null
  );

2. איסוף מידע

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

2. א. אימות הדרישות לרכישה דיגיטלית

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

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

מהכרטיסייה סצנות, מוסיפים סצנה חדשה בשם DigitalPurchaseCheck.
בקטע מילוי משבצת, לוחצים על הסמל + כדי להוסיף משבצת חדשה.
בקטע בחירת סוג, בוחרים את actions.type.DigitalPurchaseCheckResult בתור סוג יחידת הקיבולת.
בשדה 'שם מיקום', מזינים למשבצת את השם DigitalPurchaseCheck.
מפעילים את תיבת הסימון התאמה אישית של כתיבת ערך מיקום בדף (מופעלת כברירת מחדל).
לוחצים על שמירה.

בדיקת רכישה דיגיטלית תוביל לאחת מהתוצאות הבאות:

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

כדי לטפל בתוצאה של בדיקת רכישה בדיגיטל, צריך לפעול לפי השלבים הבאים:

בכרטיסייה סצנות, בוחרים את הסצנה החדשה שיצרתם ב-DigitalPurchaseCheck.
בקטע תנאי, לוחצים על הסמל + כדי להוסיף תנאי חדש.
בשדה הטקסט, מזינים את תחביר התנאי הבא כדי לבדוק אם תנאי להצלחה:
```
scene.slots.status == "FINAL" && session.params.DigitalPurchaseCheck.resultType == "CAN_PURCHASE"
```
מעבירים את העכבר מעל התנאי שהוספתם ולוחצים על החץ למעלה. כדי להציב אותו לפני if scene.slots.status == "FINAL".
מפעילים את האפשרות שליחת הנחיות ומספקים הנחיה פשוטה כדי ליידע את המשתמש הם מוכנים לבצע עסקה:
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            You are ready to purchase digital goods.
```
בקטע מעבר, בוחרים סצנה אחרת ומאפשרים למשתמש להמשיך את השיחה ולהמשיך לביצוע עסקה.
בוחרים את התנאי else if scene.slots.status == "FINAL".
מפעילים את האפשרות שליחת הנחיות ומספקים הנחיה פשוטה כדי ליידע את המשתמש הם לא יכולים לבצע עסקה:
```
candidates:
  - first_simple:
      variants:
        - speech: Sorry you cannot perform a digital purchase.
```
בקטע מעבר, בוחרים באפשרות סיום השיחה כדי לסיים את השיחה.

2. ב. איסוף מלאי זמין

משתמשים ב-API של הרכישות הדיגיטליות כדי לבקש את חנות Play שזמינה כרגע ואחר כך בונים מערך אובייקטים של JSON לכל מוצר. תתבצע הפניה למערך הזה מאוחר יותר כדי להראות למשתמש אילו אפשרויות זמינות לרכישה.

כל אחד מהמוצרים הדיגיטליים שלכם מיוצג כמק"ט בפורמט JSON. הקוד הבא של Node.js מתאר את הפורמט הצפוי של כל מק"ט:

body = {
  skus: [
    skuId: {
      skuType: one of "SKU_TYPE_IN_APP" or "SKU_TYPE_SUBSCRIPTION"
      id: string,
      packageName: string
    }
    formattedPrice: string,
    title: string,
    description: string
  ]
}

לשלוח בקשת POST https://actions.googleapis.com/v3/packages/{packageName}/skus:batchGet נקודת קצה (endpoint), כאשר {packageName} הוא שם החבילה של האפליקציה ב-Google Play למסוף (לדוגמה, com.myapp.digitalgoods), ולעצב את התוצאה מערך של אובייקטי SKU.

כדי לאחזר רק מוצרים דיגיטליים ספציפיים במערך שמתקבל, צריך לרשום את המוצר מזהים של מוצרים דיגיטליים (כפי שהם מוצגים מתחת לכל מוצר מתוך האפליקציה ב-Google Play) מסוף) שרוצים להפוך לזמינים לרכישה ב-body.ids.

הקוד הבא של Node.js מבקש רשימה של מוצרים זמינים רכישות API ומעצבות את התוצאה כמערך מק"טים:

return jwtClient.authorize((err, tokens) => {
    if (err) {
      throw new Error(`Auth error: ${err}`);
    }

    const packageName = 'com.example.projectname';

    request.post(`https://actions.googleapis.com/v3/packages/${packageName}/skus:batchGet`, {
      'auth': {
        'bearer': tokens.access_token,
      },
      'json': true,
      'body': {
        'conversationId': conv.session.id,
        'skuType': 'SKU_TYPE_IN_APP',
        // This request is filtered to only retrieve SKUs for the following product IDs
        'ids': ['consumable.1']
      },
    }, (err, httpResponse, body) => {
      if (err) {
        throw new Error(`API request error: ${err}`);
      }
      console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
      console.log(JSON.stringify(body));
    });
  });
});

3. יצירת ההזמנה

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

הקוד הבא של Node.js קורא מערך מלאי של אובייקטי SKU ויוצר תגובה לרשימה עם פריט אחד ברשימה עבור כל:

const items = [];
const entries = [];
skus.forEach((sku) => {
   const key = `${sku.skuId.skuType},${sku.skuId.id}`
   items.push({
       key: key
   });
   entries.push({
       name: key,
       synonyms: [],
       display: {
           title: sku.title,
           description: `${sku.description} | ${sku.formattedPrice}`,
       }
   });
});

conv.session.typeOverrides = [{
   name: 'type_name',
   mode: 'TYPE_REPLACE',
   synonym: {
       entries: entries
   }
}];

conv.add(new List({
   title: 'List title',
   subtitle: 'List subtitle',
   items: items,
}));

יצירת רכישה מבחירת המשתמשים

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

conv.session.params.purchase = {
  "@type": "type.googleapis.com/google.actions.transactions.v3.CompletePurchaseValueSpec",
  "skuId": {
    "skuType": "<SKU_TYPE_IN_APP>",
    "id": "<SKU_ID>",
    "packageName": "<PACKAGE_NAME>"
  },
  "developerPayload": ""
};

ב-Actions Builder אפשר להשתמש במקום זאת בעורך JSON כדי להגדיר את יחידת הקיבולת (Slot) עם אובייקט ההזמנה שלמעלה. שתי ההטמעות משתמשות באותו פורמט עבור CompletePurchaseValueSpec, שנמצא ב חומר עזר בנושא מטען ייעודי (payload) של JSON webhook.

4. משלימים את הרכישה

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

יצירת סצנה של רכישה מלאה

מהכרטיסייה סצנות, מוסיפים סצנה חדשה בשם CompletePurchase.
בקטע מילוי משבצת, לוחצים על הסמל + כדי להוסיף משבצת חדשה.
בקטע בחירת סוג, בוחרים את actions.type.CompletePurchaseValue בתור סוג משבצת הזמן.
בשדה 'שם מיקום', מזינים למשבצת את השם CompletePurchase.
מפעילים את תיבת הסימון התאמה אישית של כתיבת ערך מיקום בדף (מופעלת כברירת מחדל).
בקטע הגדרת משבצת, בוחרים באפשרות Use session parameter מהתפריט הנפתח.
בקטע הגדרת משבצת,מזינים את השם של פרמטר הסשן שישמש כדי לשמור את ההזמנה בשדה הטקסט (למשל $session.params.purchase).
לוחצים על שמירה.

5. טיפול בתוצאה

משבצת מסוג actions.type.CompletePurchaseValue יכולה לכלול את הדברים הבאים תוצאות:

PURCHASE_STATUS_OK: הרכישה בוצעה בהצלחה. העסקה היא בשלב הזה, לכן צריך לצאת מתהליך העסקאות ולחזור אל השיחה.
PURCHASE_STATUS_ALREADY_OWNED: העסקה נכשלה כי המשתמש כבר הוא הבעלים של הפריט הזה. כדי להימנע מהשגיאה הזו, אפשר לבדוק את הסרטון הקודם של המשתמש לבצע רכישות ולהתאים את הפריטים המוצגים כדי שלא תהיה להם אפשרות לרכוש מחדש פריטים שכבר נמצאים בבעלותם.
PURCHASE_STATUS_ITEM_UNAVAILABLE: העסקה נכשלה כי הפריט המבוקש אינו זמין. כדי להימנע מהשגיאה הזו, אפשר לבדוק את האפשרויות מק"טים שקרובים יותר למועד הרכישה.
PURCHASE_STATUS_ITEM_CHANGE_REQUESTED: העסקה נכשלה כי המשתמש החליט לרכוש משהו אחר. תכנון מחדש של ההזמנה כדי שהמשתמש יוכל לקבל החלטה אחרת מיד.
PURCHASE_STATUS_USER_CANCELLED: העסקה נכשלה כי המשתמש ביטל את תהליך הרכישה. מכיוון שהמשתמש יצא מהתהליך מוקדם מדי, לשאול את המשתמש אם הוא רוצה לנסות שוב לבצע את העסקה או לצאת מהעסקה בסך הכול.
PURCHASE_STATUS_ERROR: העסקה נכשלה מסיבה לא ידועה. צריך להודיע למשתמש שהעסקה נכשלה ולשאול אם הוא רוצה לנסות שוב.
PURCHASE_STATUS_UNSPECIFIED: העסקה נכשלה מסיבה לא ידועה, וכתוצאה מכך הסטטוס לא ידוע. כדי לטפל בסטטוס השגיאה, אתם יכולים לאפשר המשתמש יודע שהעסקה נכשלה ושואל אם הוא רוצה לנסות שוב.

עליך לטפל בכל אחת מהתוצאות האלה בסצנה שלך בCompletePurchase.

בכרטיסייה סצנות, בוחרים את הסצנה החדשה שיצרתם ב-CompletePurchase.
בקטע תנאי, לוחצים על הסמל + כדי להוסיף תנאי חדש.
בשדה הטקסט, מזינים את תחביר התנאי הבא כדי לבדוק אם תנאי להצלחה:
```
scene.slots.status == "FINAL" && session.params.CompletePurchase.purchaseStatus == "PURCHASE_STATUS_OK"
```
מעבירים את העכבר מעל התנאי שהוספתם ולוחצים על החץ למעלה. כדי להציב אותו לפני if scene.slots.status == "FINAL".
מפעילים את האפשרות שליחת הנחיות ומספקים הנחיה פשוטה כדי ליידע את המשתמש הם מוכנים לבצע עסקה:
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            Your purchase was successful.
```
בקטע מעבר, בוחרים באפשרות סיום השיחה כדי לסיים את השיחה.

חוזרים על השלבים שלמעלה לכל סוג של תוצאת רכישה שבה רוצים לתמוך.

6. הגדרת רכישה שחוזרת על עצמה

לאחר ביצוע עסקה בהצלחה, צריך לשלוח בקשת POST לרכישות הדיגיטליות API לצריכת הפריט, וכך המשתמש יכול לרכוש אותו שוב. שליחת בקשה אל https://actions.googleapis.com/v3/conversations/{sessionId}/entitlement:consume נקודת קצה עם מזהה הסשן שנמצא ב-session.id.

בקשת ה-POST חייבת לכלול גם את האובייקט של אסימון הרכישה שמשויך אל הרכישה של המשתמש, אפשר למצוא בבקשת ה-JSON של המשתמש בקטע packageEntitlements.entitlements.inAppDetails.inAppPurchaseData.purchaseToken

הקוד הבא שולח בקשת consume ל-API של רכישות דיגיטליות מדווח אם הבקשה הצליחה:

request.post(`https://actions.googleapis.com/v3/conversations/${conv.session.id}/entitlement:consume`, {
  'auth': {
    'bearer': tokens.access_token,
  },
  'json': true,
  'body': {
  // This purchase token is in both the purchase event and the user's entitlements
  // in their request JSON
    "purchaseToken": entitlement.purchaseToken
  },
  }, (err, httpResponse, body) => {
    if (err) {
     throw new Error(`API request error: ${err}`);
    }
  console.log(`${httpResponse.statusCode}: ${httpResponse.statusMessage}`);
  console.log(JSON.stringify(httpResponse));
  console.log(JSON.stringify(body));
  resolve(body);
});

// Make sure the consume request was successful. In production, don't notify the user; handle failures on the back end
return consumePromise.then(body => {
  const consumed = Object.keys(body).length === 0;
  if (consumed) {
    conv.add(`You successfully consumed ${id}`);
  } else {
    conv.add(`Failed to consume: ${id}`);
  }
});

לשקף את הרכישות של המשתמש

כשמשתמש שולח שאילתה לפעולה שלכם, אובייקט user של הבקשה ב-JSON כולל של הרכישות שלהם. בדיקת המידע הזה ושינוי של הפעולה על סמך התוכן שהמשתמש שילם עליו.

הקוד לדוגמה הבא מציג את האובייקט user של הבקשה שכולל את האובייקט packageEntitlements מהרכישות הקודמות מתוך האפליקציה שהם ביצעו עבור חבילת com.digitalgoods.application:

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
      "packageEntitlements": [
        {
          "packageName": "com.digitalgoods.application",
          "entitlements": [
            {
              "sku": "non-consumable.1",
              "skuType": "SKU_TYPE_IN_APP"
            }
            {
              "sku": "consumable.2",
              "skuType": "SKU_TYPE_IN_APP"
            }
          ]
        },
        {
          "packageName": "com.digitalgoods.application",
          "entitlements": [
            {
              "sku": "annual.subscription",
              "skuType": "SKU_TYPE_SUBSCRIPTION",
              "inAppDetails": {
                "inAppPurchaseData": {
                  "autoRenewing": true,
                  "purchaseState": 0,
                  "productId": "annual.subscription",
                  "purchaseToken": "12345",
                  "developerPayload": "HSUSER_IW82",
                  "packageName": "com.digitalgoods.application",
                  "orderId": "GPA.233.2.32.3300783",
                  "purchaseTime": 1517385876421
                },
                "inAppDataSignature": "V+Q=="
              }
            }
          ]
        }
      ]
     }
   },
  "homeStructure": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

בדיקת הפרויקט

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

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