הנחיות לשילוב הקצה העורפי למונטיזציה מחוץ לחיוב ב-Google Play

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

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

דיווח על עסקאות חיצוניות חדשות ל-Google Play

שילוב עם Externaltransactions APIs כדי לדווח על עסקאות שמתרחשות מחוץ למערכת החיוב של Google Play מדינות נתמכות, כולל עסקאות בסכום של $0 כתוצאה מתקופת ניסיון בחינם רכישות. עסקאות במערכות חיוב חלופיות או במערכות של מבצעים חיצוניים יש להתחיל את הדיווח ולדווח עליהם רק במדינות כשירות של משתמשים, כפי שמותר באמצעות מערכת חיוב חלופית או תוכנות של מבצעים חיצוניים. אחרת הקריאה ל-API תהיה נדחה. זה חל על כל העסקאות, כולל רכישות חדשות, חידושים, פריטים נוספים, שדרוגים, שדרוגים לאחור ועוד.

דיווח חיצוני על עסקאות

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

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

דיווח על רכישה חדשה

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

הקובץ של הexternalTransactionToken שהאפליקציה קיבלה דרך UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener או ExternalOfferReportingDetailsListener קריאות חוזרות (callback) דרושות גם הן כחלק מ גוף הבקשה לרכישות חד-פעמיות ולעסקאות ראשונות רכישה חוזרת (למשל, מינוי). בכל מקרה, הפעולה הזו נקראת עסקה ראשונית. לאחר העסקה הראשונית, אין יותר צורך בexternalTransactionToken, ובשלב הבא מדווחים עסקאות (כמו חידושי מינויים) על ידי מתן מאפיין externalTransactionId. מידע נוסף זמין בקטע דיווח על עסקאות שבוצעו לאחר מכן בנוגע לרכישה. לקבלת פרטים נוספים על דיווח על עסקאות נוספות.

דוגמה:

1. המפתח מגדיר מערכת חיוב חלופית ומפעילים אותה באפליקציה שלו.
2. משתמש 1 נמצא בקוריאה הדרומית במדינה נתמכת ומנסה לקנות product1 במחיר של 12634.10KRW לחודש, עם הצעה לתקופת ניסיון בחינם למשך חודש.
3. האפליקציה מתחילה את תהליך הרכישה עם ProductDetails עבור product1 והמבצע שהמשתמש בחר.
4. משתמש 1 בוחר את מערכת החיוב החלופית של המפתח.
5. השדה UserChoiceBillingListener מקבל את הערך my_token בתור externalTransactionToken.
6. לאחר מכן המפתח שולח את המידע הרלוונטי לקצה העורפי שלו (ערך של externalTransactionToken ומוצרים שנרכשו). לאחר מכן, הן להשיק את תהליך הרכישה עבור product1 במערכת חיוב חלופית. לעסקה הזו מוקצה מזהה עסקה ייחודי בצד המפתח שמשמש לדיווח עליו ל-Google Play: 123-456-789. מזהה העסקה אף על פי שהמשתמש מקבל תקופת ניסיון בחינם.
7. לאחר שהעסקה עבור הרכישה מתרחשת במערכת חיוב חלופית המערכת מדווחת על העסקה ל-Google Play באמצעות בעקבות הבקשה הבאה. בהתחלה היא תדווח כעסקה בסך אפס דולר כי המשתמש מקבל חודש בחינם.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

הערה: subscriptionType יכול להיות RECURRING (למינויים שמתחדשים אוטומטית) או PREPAID (למינויים בתשלום מראש).

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

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

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

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

דיווח על עסקאות נוספות שבוצעו בעקבות רכישה

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

בהמשך לדוגמה הקודמת:

1. החידוש הראשון של משתמש 1 מתבצע במערכת חיוב חלופית. התגובה הראשונית מזהה העסקה היה 123-456-789.
2. המפתח מדווח על חזרה של העסקאות בפרמטר של השאילתה בכתובת ה-URL. בתור מזהה העסקה החיצוני של העסקה החדשה, תוך התייחסות מזהה העסקה החיצוני של העסקה הראשונית שדה initialExternalTransactionId.

דוגמה לבקשה:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

דיווח על שדרוג או שדרוג לאחור

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

מעבר מדיווח ידני על עסקאות במערכת חיוב חלופית

הערה: דיווח ידני על מערכת חיוב חלופית בלבד ועל חיוב לבחירת המשתמש עומדת בשקיעה. לפרטים נוספים על המועדים האחרונים להעברה: הסבר על החיוב לבחירת המשתמש ב-Google Play חשוב כדי להעביר את כל המינויים הפעילים שהתחילו בזמן שהצעת מערכת חיוב חלופית ללא דיווח אוטומטי דרך 'עסקאות חיצוניות' API לפני השבתת הדיווח הידני.

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

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

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

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

דוגמה לבקשה:

# Note that the externalTransactionId specified here will used to report subsequent
# transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

דיווח על תוכניות שותפים של Play

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

דיווח ל-Google Play על החזרים כספיים על רכישות

שילוב עם ה-API של Externaltransactions כדי לדווח על עסקאות שההחזר הכספי אליהן בוצע משתמשים מחוץ למערכת החיוב של Google Play. כדי שמערכת Play תזהה נכון ניתן החזר כספי על העסקה, עליך לכלול את externalTransactionId עבור העסקה שדווחה בעבר במסגרת פרמטרים של כתובת אתר.

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

דוגמה: נניח שמינוי כולל את העסקאות הבאות:

• עסקה ראשונית עם מזהה עסקה חיצוני ABC.1234-5678-9012-34567
• העסקה החוזרת הראשונה עם מזהה עסקה חיצוני ABC.1234-5678-9012-34567..0
• העסקה החוזרת השנייה עם מזהה עסקה חיצוני ABC.1234-5678-9012-34567..1

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

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

מכסות API

ממשק ה-API של Externaltransactions כפוף למכסות יומיות של ממשקי API לכל הקריאות, בדיוק כמו לכל נקודת קצה אחרת ב-Google Play Developer API.

בנוסף, ב-API של Externaltransactions יש 1,200 שאילתות בדקה מגבלת (QPM) על שיחות ל-Externaltransactions.createexternaltransaction או Externaltransactions.refundexternaltransaction. שיחות אל Externaltransactions.getexternaltransaction לא נספרים במסגרת 1,200 QPM המוגבלות של המשאבים.