במדריך הזה מוסבר איך לשלב את ממשקי ה-API כדי להציע מערכת חיוב חלופית בלבד (כלומר, בלי אפשרות בחירה למשתמשים) באפליקציות שעומדות בדרישות. מידע נוסף על התוכניות האלה, כולל דרישות הסף וההיקף הגיאוגרפי, זמין במאמר מידע על חיוב חלופי.
הגדרה של ספריית החיובים ב-Play
עליכם להוסיף את התלות של ספריית החיובים ב-Play לאפליקציית Android. כדי להשתמש בממשקי API של מערכות חיוב חלופיות נדרשת גרסה 6.1 ואילך.
חיבור ל-Google Play
השלבים הראשונים בתהליך השילוב זהים לאלה שמתוארים במדריך לשילוב של חיוב ב-Google Play, אבל יש כמה שינויים כשמפעילים את BillingClient:
- כדי לציין שהאפליקציה שלכם משתמשת רק במערכת חיוב חלופית, אתם צריכים להפעיל method חדש:
enableAlternativeBillingOnly.
בדוגמה הבאה מוצג אתחול של BillingClient כולל השינויים האלה:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableAlternativeBillingOnly()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableAlternativeBillingOnly()
.build();
אחרי שמפעילים את BillingClient, צריך ליצור חיבור ל-Google Play כמו שמתואר במדריך השילוב.
בדיקת זמינות
כדי לוודא שזמינה באפליקציה רק מערכת חיוב חלופית, צריך להפעיל את isAlternativeBillingOnlyAvailableAsync.
ה-API הזה יחזיר BillingResponseCode.OK אם זמינה רק מערכת חיוב חלופית. בקטע טיפול בתגובות מוסבר איך האפליקציה צריכה להגיב לקודי תגובה אחרים.
Kotlin
billingClient.isAlternativeBillingOnlyAvailableAsync(object:
AlternativeBillingOnlyAvailabilityListener {
override fun onAlternativeBillingOnlyAvailabilityResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling alternative billing only being unavailable, etc.
return
}
// Alternative billing only is available. Continue with steps in
// the guide.
}
});
Java
billingClient.isAlternativeBillingOnlyAvailable(
new AlternativeBillingOnlyAvailabilityListener() {
@Override
public void onAlternativeBillingOnlyAvailabilityResponse(
BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling alternative billing only being unavailable,
// etc.
return;
}
// Alternative billing only is available. Continue with steps in
// the guide.
}
});
תיבת דו-שיח עם מידע למשתמשים
כדי לשלב רק מערכת חיוב חלופית, האפליקציה שעומדת בדרישות צריכה להציג מסך מידע שעוזר למשתמשים להבין שהחיוב לא ינוהל על ידי Google Play. צריך להציג למשתמשים את מסך המידע באמצעות קריאה ל-API showAlternativeBillingOnlyInformationDialog לפני שמתחילים את תהליך מערכת החיוב החלופית בכל פעם. אם המשתמש כבר אישר את תיבת הדו-שיח, בדרך כלל השימוש ב-API הזה לא יגרום להצגת תיבת הדו-שיח שוב. יכול להיות שתיבת הדו-שיח תוצג שוב למשתמש במצבים כמו מחיקת מטמונים במכשיר.
Kotlin
// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;
val listener : AlternativeBillingOnlyInformationDialogListener =
AlternativeBillingOnlyInformationDialogListener {
override fun onAlternativeBillingOnlyInformationDialogResponse(
billingResult: BillingResult) {
// check billingResult
}
}
val billingResult =
billingClient.showAlternativeBillingOnlyInformationDialog(activity,
listener)
Java
// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;
AlternativeBillingOnlyInformationDialogListener listener =
new AlternativeBillingOnlyInformationDialogListener() {
@Override
public void onAlternativeBillingOnlyInformationDialogResponse(
BillingResult billingResult) {
// check billingResult
}
};
BillingResult billingResult =
billingClient.showAlternativeBillingOnlyInformationDialog(activity,
listener);
אם השיטה הזו מחזירה BillingResponseCode.OK, האפליקציה יכולה להמשיך בעסקה. במקרה של BillingResponseCode.USER_CANCELED, האפליקציה צריכה להפעיל את showAlternativeBillingOnlyInformationDialog כדי להציג שוב את תיבת הדו-שיח למשתמש. בקטע טיפול בתגובות מוסבר איך האפליקציה צריכה להגיב לקודי תגובה אחרים.
דיווח על עסקאות ל-Google Play
כל העסקאות שבוצעו דרך מערכת חיוב חלופית חייבות להיות מדווחות ל-Google Play באמצעות קריאה ל-ממשק API של Google Play למפתחים מהבק-אנד תוך 24 שעות, עם externalTransactionToken שמתקבל באמצעות ממשק ה-API שמתואר בהמשך. צריך ליצור externalTransactionToken חדש לכל רכישה חד-פעמית, לכל מינוי חדש ולכל שדרוג או שנמוך של מינוי קיים. במדריך לשילוב עם הבק-אנד מוסבר איך לדווח על עסקה אחרי שמקבלים externalTransactionToken.
Kotlin
billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
AlternativeBillingOnlyReportingDetailsListener {
override fun onAlternativeBillingOnlyTokenResponse(
billingResult: BillingResult,
alternativeBillingOnlyReportingDetails:
AlternativeBillingOnlyReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
alternativeBillingOnlyReportingDetails?
.externalTransactionToken
// Send transaction token to backend and report to Google Play.
}
});
Java
billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
new AlternativeBillingOnlyReportingDetailsListener() {
@Override
public void onAlternativeBillingOnlyTokenResponse(
BillingResult billingResult,
@Nullable AlternativeBillingOnlyReportingDetails
alternativeBillingOnlyReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
alternativeBillingOnlyReportingDetails
.getExternalTransactionToken();
// Send transaction token to backend and report to Google Play.
}
});
טיפול בתגובות
יכול להיות שהשיטות שלמעלה isAlternativeBillingOnlyAvailableAsync(),
showAlternativeBillingOnlyInformationDialog() ו-createAlternativeBillingOnlyReportingDetailsAsync() יחזירו תגובות שאינן BillingResponseCode.OK במקרה של שגיאות. בהמשך מפורטות ההמלצות לטיפול בשגיאות:
-
ERROR: זו שגיאה פנימית. לא להמשיך בתהליך התשלום. אפשר לנסות שוב על ידי הפעלת הקריאהshowAlternativeBillingOnlyInformationDialog()כדי להציג למשתמש את תיבת הדו-שיח עם המידע בפעם הבאה שהוא ינסה לבצע רכישה. -
FEATURE_NOT_SUPPORTED: חנות Play לא תומכת בממשקי ה-API של מערכת החיוב החלופית במכשיר הנוכחי. לא להמשיך בתהליך התשלום. USER_CANCELED: לא להמשיך בעסקה. שלחו קריאה חדשה ל-showAlternativeBillingOnlyInformationDialog()כדי שהמשתמש יראה את תיבת הדו-שיח עם המידע בפעם הבאה שהוא ינסה לבצע רכישה.-
BILLING_UNAVAILABLE: העסקה לא עומדת בדרישות לשימוש בחיוב חלופי בלבד, ולכן לא ניתן להמשיך אותה במסגרת התוכנית הזו. יכול להיות שהמשתמש לא נמצא במדינה שעומדת בדרישות של התוכנית הזו, או שלא הצלחתם לרשום את החשבון שלכם לתוכנית. אם מדובר במקרה השני, צריך לבדוק את סטטוס ההרשמה ב-Play Console. -
DEVELOPER_ERROR: יש שגיאה בבקשה. כדאי להשתמש בהודעת ניפוי הבאגים כדי לזהות את השגיאה ולתקן אותה לפני שממשיכים. -
NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: אלה שגיאות זמניות שכדאי לנסות שוב. במקרה שלSERVICE_DISCONNECTED, צריך ליצור מחדש חיבור ל-Google Play לפני שמנסים שוב.
בדיקת מערכת חיוב חלופית
כדי לבדוק את השילוב של מערכת החיוב החלופית, צריך להשתמש בבודקי רישיונות. לא תקבלו חשבוניות על עסקאות שבוצעו על ידי חשבונות לבדיקת רישיונות. מידע נוסף על הגדרת בודקי רישיונות זמין במאמר בנושא בדיקת חיובים על רכישות באפליקציות באמצעות רישוי אפליקציות.
השלבים הבאים
אחרי שתסיימו את השילוב באפליקציה, תוכלו לשלב את הבק-אנד.