במדריך הזה מוסבר איך מוסיפים טרנזקציות של מינויים דיגיטליים לשיחות פעולה שמאפשרת למשתמשים לרכוש את המינויים שלכם.
מונחים עיקריים: מוצר דיגיטלי למינויים הוא יחידה לניהול מלאי (מק"ט) דורש חיוב קבוע למשתמש, כמו כתב עת באינטרנט. הדבר שונה ממוצר דיגיטלי מתכלה שעליו המשתמש נדרש באופן ידני רכישה חוזרת, או מוצר דיגיטלי שלא ניתן לשימוש, שמוגדר אוטומטית נרכש פעם אחת בלבד.
לקבלת מידע נוסף על מינויים דיגיטליים, אפשר לעיין ב-Android התיעוד מופעל תכונות ספציפיות למינוי.
הנחיות בנושא הגבלות ובדיקה
כללי מדיניות נוספים חלים על 'פעולות עם עסקאות'. התהליך עשוי להימשך שבועות כדי לבדוק פעולות שכוללות עסקאות, לכן קח בחשבון את הזמן ומתכננים את לוח הזמנים לפרסום. כדי להקל על תהליך הבדיקה, חשוב להקפיד לעמוד בדרישות עם מדיניות והנחיות בנושא עסקאות לפני שליחת הפעולה לבדיקה.
אפשר לפרוס פעולות למכירת מוצרים דיגיטליים רק במדינות הבאות:
- אוסטרליה
- ברזיל
- קנדה
- אינדונזיה
- יפן
- מקסיקו
- רוסיה
- סינגפור
- תאילנד
- טורקיה
- בריטניה
- ארצות הברית
תהליך העסקה
מדריך זה מתאר כל שלב בפיתוח כפי שהוא מתרחש במוצרים דיגיטליים תהליך העסקה. כשהפעולה מטפלת בעסקאות של מוצרים דיגיטליים, משתמשת בתהליך הבא:
- מגדירים לקוח API לרכישות דיגיטליות: הפעולה משתמשת רכישות API לתקשורת עם המלאי שלך ב-Google Play וביצוע עסקאות. לפני שהפעולה מבצעת פעולה אחרת, היא יוצרת לקוח JWT עם מפתח שירות לתקשורת עם ממשק ה-API של רכישות דיגיטליות.
- איסוף מידע: הפעולה אוספת מידע בסיסי על
ואת המלאי שלכם ב-Google Play כהכנה לעסקה.
- לאמת את הדרישות לעסקאות: הפעולה מתבססת על הדרישות לעסקאות בתחילת תהליך הרכישה, ולוודא שהמשתמש יכול לבצע עסקאות.
- איסוף מלאי זמין: הפעולה בודקת את חשבון Google Play שלכם של מלאי המוצרים שלו ומזהה אילו פריטים זמינים כרגע לרכישה.
- יוצרים את ההזמנה: הפעולה מציגה את המוצרים הדיגיטליים הזמינים כדי למשתמשים, כדי שהם יוכלו לבחור אחד לרכישה.
- השלמת הרכישה: הפעולה משתמשת ב-API של רכישות דיגיטליות כדי ליזום רכישה עם בחירת המשתמש בחנות Google Play.
- טיפול בתוצאה: הפעולה מקבלת קוד סטטוס של עסקה ומיידע את המשתמש שהרכישה הצליחה (או לוקחת שלבים נוספים).
דרישות מוקדמות
לפני שמשלבים עסקאות דיגיטליות בפעולה, צריך הדרישות המוקדמות:
א' חשבון פיתוח וגם חשבון של מוכר/ת ב-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, מבצעים את השלבים הבאים:
- נכנסים אל Build (יצירת חבילה / APK חתומה) ויצירת חבילה חתומה / APK.
- לוחצים על הבא.
- בקטע Key store path (נתיב מאגר מפתחות), לוחצים על Create new (יצירת חדש).
- ממלאים כל אחד מהשדות ולוחצים על אישור. חשוב לרשום את חנות המפתחות שלך סיסמה וסיסמאות מפתחות, ושמרו אותן במקום בטוח, תשתמש בהם בהמשך.
- לוחצים על הבא.
- בוחרים גרסה.
- בוחרים באפשרות V1 (JAR Signature).
- לוחצים על סיום.
- אחרי כמה שניות, מערכת Android Studio יוצרת קובץ
app-release.apk
. איתור הקובץ לשימוש במועד מאוחר יותר.
ב Google Play Console, יוצרים אפליקציה חדשה.
עוברים אל גרסאות של אפליקציות.
בקטע מסלולים סגורים, עוברים אל ניהול ואז אלפא.
לוחצים על הלחצן Create Release (יצירת גרסה).
בקטע מתן הרשאה ל-Google לנהל את מפתח החתימה שלך ולהגן עליו, מזינים את החתימה שלכם מידע חשוב.
מעלים את קובץ ה-APK.
לוחצים על שמירה.
יצירת מוצרים דיגיטליים
אם אין לך כרגע מוצרים דיגיטליים ב-Play Console, צריך לפעול לפי השלבים הבאים שלבים:
- ב Google Play Console, עוברים אל מוצרים מתוך האפליקציה ואז אל מינויים. אם מוצגת אזהרה, פועלים לפי ההוראות הקודמות כדי ליצור אפליקציה ל-Android או לוחצים על הקישור כדי ליצור פרופיל מוכר.
- לוחצים על יצירת מינוי.
- ממלאים את השדות של המוצר הדיגיטלי. שימו לב למזהה המוצר כך תפנו למוצר הזה מהפעולה.
- לוחצים על שמירה.
- חוזרים על שלבים 2 עד 4 לכל מוצר שרוצים למכור.
מכינים את פרויקט הפעולות
כשהמוצרים הדיגיטליים שלך מוגדרים ב-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.
אם עדיין לא קישרתם אף נכס, קודם צריך לקשר אתר:
- לחץ על הלחצן של נכס האינטרנט (</>).
- מזינים את כתובת ה-URL של דומיין האינטרנט ולוחצים על קישור.
Google תשלח אימייל עם הוראות נוספות לאדם לעבור אימות עבור דומיין האינטרנט הזה Google Search Console. אחרי שנמען האימייל יבצע את השלבים האלה, האתר אמור יופיעו בקטע אימות המותג.
לאחר שיש לך לפחות אתר מקושר אחד, מבצעים את השלבים הבאים כדי: חיבור אפליקציית Android:
- במסוף Actions, נכנסים אל Deploy ואז אל Brand verification.
- לחץ על חבר אפליקציה.
בדף שמופיע, פועלים לפי ההוראות לאימות כתובת האינטרנט הדומיין ב-Play Console. בוחרים את אפליקציית Play שמכילה את מוצרים דיגיטליים ולהזין את כתובת האתר של דומיין האינטרנט בדיוק כפי שהיא מוצגת אימות המותג.
שוב, Google שולחת הודעת אימות לבעלים המאומת של הדומיין. לאחר שאפליקציית Play תאשר את האימות, האפליקציה שלך ב-Play יופיעו בקטע אימות המותג.
מפעילים את האפשרות גישה לרכישות ב-Play.
בניית תהליך הרכישה
בעזרת הכנת פרויקט 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. א. אימות הדרישות בנוגע לעסקאות
מומלץ לוודא שהחשבון של המשתמש מוגדר להניב ביצועים טובים
לפני שנותנים להם אפשרות לבצע רכישה. השלב הזה
כולל בדיקה של המשתמש הגדיר אמצעי תשלום, ושהוא שייך
מקום שבו יש תמיכה בעסקאות דיגיטליות. בתחילת העסקה
, יש להשתמש בעוזר DIGITAL_PURCHASE_CHECK
כדי לאמת את העסקה של המשתמש
את ההגדרות האישיות של Assistant.
קוד Node.js הבא משתמש ב-DIGITAL_PURCHASE_CHECK
בתחילת
call:
app.intent('Default Welcome Intent', async (conv, { SKU }) => {
// Immediately invoke digital purchase check intent to confirm
// purchase eligibility.
conv.ask(new DigitalPurchaseCheck());
});
מצאו את התוצאה של הבדיקה הזו בארגומנטים של השיחה
DIGITAL_PURCHASE_CHECK_RESULT
על סמך התוצאה הזו, ממשיכים
תהליך של ביצוע עסקה או שינוי מוצר, ולבקש ממנו לבדוק את Google Pay
הגדרה אישית.
הקוד הבא של Node.js מטפל בתוצאה של בדיקת הדרישות :
app.intent('Digital Purchase Check', async (conv) => {
const arg = conv.arguments.get('DIGITAL_PURCHASE_CHECK_RESULT');
if (!arg || !arg.resultType) {
conv.close('Digital Purchase check failed. Please check logs.');
return;
}
// User does not meet necessary conditions for completing a digital purchase
if (arg.resultType === 'CANNOT_PURCHASE' || arg.resultType === 'RESULT_TYPE_UNSPECIFIED') {
conv.close(`It looks like you aren't able to make digital purchases. Please check your Google Pay configuration and try again.`);
return;
}
conv.ask('Welcome to the Digital Goods Sample. Would you like to see what I have for sale?');
});
2. ב. איסוף מלאי זמין
משתמשים ב-API של הרכישות הדיגיטליות כדי לבקש את חנות Play שזמינה כרגע ואחר כך בונים מערך אובייקטים של JSON לכל מוצר. תתבצע הפניה למערך הזה מאוחר יותר כדי להראות למשתמש אילו אפשרויות זמינות לרכישה.
כל אחד מהמוצרים הדיגיטליים שלכם מיוצג כמק"ט בפורמט JSON. הקוד הבא של Node.js מתאר את הפורמט הצפוי של כל מק"ט:
body = {
skus: [
skuId: {
skuType: one of "APP" or "UNSPECIFIED"
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': conversationId,
'skuType': 'APP',
// This request is filtered to only retrieve SKUs for the following product IDs
'ids': ['annual.subscription']
},
}, (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 ויוצר תגובה לרשימה עם פריט אחד ברשימה עבור כל:
skus.forEach((sku) => {
const key = `${sku.skuId.skuType},${sku.skuId.id}`
list.items[key] = {
title: sku.title,
description: `${sku.description} | ${sku.formattedPrice}`,
};
});
4. משלימים את הרכישה
כדי להשלים את הרכישה, צריך להשתמש בכוונת העוזר COMPLETE_PURCHASE
עם
הפריט שהמשתמש בחר.
הקוד הבא של Node.js מטפל בבחירת המק"ט של המשתמש מתשובה לרשימה
ומבקש את ה-Intent COMPLETE_PURCHASE
עם המידע הזה:
app.intent('Send Purchase', (conv, params, option) => {
let [skuType, id] = option.split(',');
conv.ask(new CompletePurchase({
skuId: {
skuType: skuType,
id: id,
packageName: <PACKAGE_NAME>,
},
}));
});
5. טיפול בתוצאה
בסיום הרכישה, יופעל actions_intent_COMPLETE_PURCHASE
אירוע ב-Dialogflow (או actions.intent.COMPLETE_PURCHASE
Actions SDK) עם
ארגומנט COMPLETE_PURCHASE_VALUE
שמתאר את התוצאה. בונים כוונה,
שמופעל על ידי האירוע הזה, והתוצאה מועברת למשתמש.
צריך לטפל בתוצאות הרכישה הבאות:
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
: העסקה נכשלה מסיבה לא ידועה, וכתוצאה מכך הסטטוס לא ידוע. כדי לטפל בסטטוס השגיאה, צריך לאפשר למשתמש לדעת שהעסקה נכשלה ולשאול אם הוא רוצה לנסות שוב.
קוד Node.js הבא קורא את הארגומנט COMPLETE_PURCHASE_VALUE
ו
מטפל בכל תוצאה:
app.intent('Purchase Result', (conv) => {
const arg = conv.arguments.get('COMPLETE_PURCHASE_VALUE');
console.log('User Decision: ' + JSON.stringify(arg));
if (!arg || !arg.purchaseStatus) {
conv.close('Purchase failed. Please check logs.');
return;
}
if (arg.purchaseStatus === 'PURCHASE_STATUS_OK') {
conv.close(`Purchase completed! You're all set!`);
} else if (arg.purchaseStatus === 'PURCHASE_STATUS_ALREADY_OWNED') {
conv.close('Purchase failed. You already own this item.');
} else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_UNAVAILABLE') {
conv.close('Purchase failed. Item is not available.');
} else if (arg.purchaseStatus === 'PURCHASE_STATUS_ITEM_CHANGE_REQUESTED') {
// Reprompt with your item selection dialog
} else {
conv.close('Purchase Failed:' + arg.purchaseStatus);
}
});
לשקף את הרכישות של המשתמש
כשמשתמש שולח שאילתה לפעולה שלכם, אובייקט user
של בקשת ה-JSON כולל רשימה
של הרכישות שלהם. בדיקת המידע הזה ושינוי התשובה של הפעולה
על סמך התוכן שהמשתמש שילם עליו.
הקוד לדוגמה הבא מציג את האובייקט user
של הבקשה שכולל את האובייקט
packageEntitlements
מהרכישות הקודמות מתוך האפליקציה שהם ביצעו עבור
חבילת com.digitalgoods.application
:
"user": {
"userId": "xxxx",
"locale": "en-US",
"lastSeen": "2018-02-09T01:49:23Z",
"packageEntitlements": [
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "non-consumable.1",
"skuType": "APP"
}
{
"sku": "consumable.2",
"skuType": "APP"
}
]
},
{
"packageName": "com.digitalgoods.application",
"entitlements": [
{
"sku": "annual.subscription",
"skuType": "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=="
}
}
]
}
]
},
"conversation": {
"conversationId": "1518141160297",
"type": "NEW"
},
"inputs": [
{
"intent": "actions.intent.MAIN",
"rawInputs": [
{
"inputType": "VOICE",
"query": "Talk to My Test App"
}
]
}
],
...
}