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

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

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

מילון מונחים

מוסכמות המונחים במדריך הזה:

  • תוכניות חיוב וקישורים: תוכניות שמאפשרות לרכוש תוכן דיגיטלי או להוריד אפליקציות מחוץ ל-Google Play. התוכניות האלה כוללות את התוכניות מערכת חיוב חלופית ותוכן חיצוני.
  • ‫External Transactions API: ממשקי API שמשמשים לדיווח על עסקאות בתוכניות חיוב וקישורים שעומדות בדרישות.
  • עסקה חיצונית: עסקה שעומדת בדרישות ומתרחשת מחוץ לאפליקציה, כפי שמוגדר בתוכניות מערכת חיוב חלופית ותוכן חיצוני.
  • טוקן לעסקה חיצונית: טוקן שספריית החיוב של Play מספקת לכם, כדי שתוכלו להשתמש בו כשהמשתמש מבצע עסקה חיצונית. הטוקן הזה משמש כדי להודיע ל-Google Play על עסקה חיצונית מורשית.
  • מזהה עסקה חיצונית: מזהה ייחודי שאתם יוצרים כדי לזהות עסקה חיצונית.

הגדרת ההרשאות ב-Play Console

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

במאמר שימוש בחשבון שירות מוסבר איך יוצרים חשבון שירות ונותנים הרשאות ב-Play Console. מידע נוסף על ההרשאות ב-Play Console זמין במאמר הוספת משתמשים לחשבון הפיתוח וניהול הרשאות.

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

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

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

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

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

דיווח על עסקה ראשונית

בכל פעם שמאושרת רכישה חדשה או הורדה של אפליקציה בתוכניות החיוב והקישור, צריך להפעיל את ה-API של externaltransactions.

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

דוגמה:

  1. המפתח מגדיר ומפעיל מערכת חיוב חלופית באפליקציה שלו.
  2. משתמש 1 נמצא בדרום קוריאה, מדינה נתמכת, ומנסה לקנות את product1 במחיר של 12,634.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$, ואחריה עסקה שנייה במועד מאוחר יותר במחיר המק"ט כשההזמנה מראש מתממשת. בקטע דיווח על עסקאות עוקבות של רכישה מוסבר איך לדווח על עסקאות עוקבות.
  • כשמדווחים על עסקאות ראשוניות במבצעים חיצוניים, צריך לציין את הערך ExternalOfferDetails. לא צריך לעשות את זה בעסקאות הבאות.

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

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"
 }
}

מבצעים חיצוניים

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

  • כשמדווחים על עסקאות של הורדת אפליקציות, צריך להגדיר את linkType ל-LINK_TO_APP_DOWNLOAD ולציין את הערכים המתאימים ל-installedAppPackage ול-installedAppCategory. פרטים נוספים זמינים במאמר דיווח על הורדת אפליקציה.
  • כשמדווחים על עסקאות של מבצעים על תוכן דיגיטלי, מגדירים את linkType בתור LINK_TO_DIGITAL_CONTENT_OFFER.
  • אחרי שמתקינים אפליקציה של צד שלישי דרך התוכנית "מבצעים חיצוניים", צריך לדווח על עסקאות שבוצעו באפליקציה של הצד השלישי. כשמדווחים על העסקאות האלה, צריך לקשר אותן לאירוע ההורדה המקורי של האפליקציה:
    • מציינים את externalTransactionToken מאירוע הורדת האפליקציה.
    • בשדה externalOfferDetails, מגדירים את appDownloadEventExternalTransactionId לערך externalTransactionId של אירוע הורדת האפליקציה. שדות אחרים ב-externalOfferDetails הם לא חובה.

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

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI

Body
 {
"originalPreTaxAmount" : {
   "priceMicros" : "990000", # 0.99 EUR
   "currency" : "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros" : "90000", # 0.09 EUR
   "currency" : "EUR"
 },
"transactionTime" : "2025-11-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken" : "my_external_transaction_token_for_link_to_download_event"
 },
 "userTaxAddress" : {
   "regionCode" : "DE"
 },
 "externalOfferDetails" : {
   "appDownloadEventExternalTransactionId" : "my_external_transaction_id_for_link_to_download_event"
 }
}

הפרטים המעודכנים של עמלת השירות של Play Services לסוגי עסקאות שונים מופיעים במאמר שינויים בתוכנית לשיווק מחוץ לאפליקציה למשתמשים באזור הכלכלי האירופי (EEA).

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

במקרים מסוימים, יש יותר מתשלום אחד של משתמש שמשויך לאותה רכישה חיצונית, למשל חידושי מינויים או הוספת כסף למינוי בתשלום מראש. אפשר לדווח על העסקאות הבאות באמצעות אותו 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", # 12634 KRW
   "currency" : "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros" : "1263000000", # 1263 KRW
   "currency" : "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId" : "123-456-789",

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

דיווח על שדרוג או שנמוך

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

דיווח על הורדת אפליקציה

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

דוגמה לבקשה:

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

Body
 {
"originalPreTaxAmount" : {
   "priceMicros" : "0",
   "currency" : "USD"
 },
 "originalTaxAmount" : {
   "priceMicros" : "0",
   "currency" : "USD"
 },
"transactionTime" : "2025-12-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken" : "my_token",
 },
 "userTaxAddress" : {
   "regionCode" : "US"
 },
 "externalOfferDetails" : {
   "linkType" : "LINK_TO_APP_DOWNLOAD",
   "installedAppPackage" : "my.external.app",
   "installedAppCategory" : "APP"
 }
}

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

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

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

אפשר להשתמש בשדה 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 על החזרים כספיים של רכישות

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

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

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

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

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

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

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

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

מכסות ל-API

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

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