راهنمای ادغام Backend برای کسب درآمد خارج از Google Play Billing

Google Play Developer API اکنون دارای قابلیت‌های اضافی برای گزارش تراکنش‌ها از سیستم صدور صورت‌حساب یا پیشنهادات خارجی است. این راهنما نحوه گزارش تراکنش های صورتحساب جایگزین یا پیشنهادات خارجی را شرح می دهد.

چند مؤلفه وجود دارد که ممکن است برای انجام خریدهای درون برنامه ای شما از باطن شما ضروری باشد. برای ایجاد آنها، باید یکپارچه سازی backend خود را همانطور که در پیکربندی Google Play Developer API نشان داده شده است، تنظیم کنید. برای همه عملکردهای پشتیبان برنامه‌نویس که مختص APIهای صورت‌حساب جایگزین یا پیشنهادات خارجی نیستند، دستورالعمل‌های مستندات سیستم صورت‌حساب Google Play اعمال می‌شود.

تراکنش های خارجی جدید را به Google Play گزارش دهید

برای گزارش تراکنش‌های خارج از سیستم صورت‌حساب Google Play در کشورهای پشتیبانی‌شده، از جمله تراکنش‌های 0 دلاری ناشی از خریدهای آزمایشی رایگان، با Externaltransactions APIs یکپارچه شوید. تراکنش‌های صورت‌حساب جایگزین یا سیستم‌های پیشنهادات خارجی باید فقط برای کشورهای کاربر واجد شرایط که تحت برنامه‌های صورت‌حساب جایگزین یا پیشنهادات خارجی مجاز است شروع و گزارش شود، در غیر این صورت تماس API رد خواهد شد. این امر برای همه تراکنش‌ها، از جمله خریدهای جدید، تمدید، شارژ، ارتقاء، کاهش رتبه و موارد دیگر اعمال می‌شود.

گزارش تراکنش خارجی

پس از تأیید پرداخت از طریق سیستم صورتحساب جایگزین یا پیشنهاد خارجی، باید با Externaltransactions API تماس بگیرید تا یک تراکنش خارجی را گزارش کنید. این امر برای همه تراکنش‌ها، از جمله هزینه‌های اولیه، تمدید، بازپرداخت و موارد دیگر اعمال می‌شود. همه تراکنش‌ها باید ظرف 24 ساعت پس از انجام معامله گزارش شوند.

هر تراکنش خارجی با شناسه تراکنش خارجی گزارش می شود. برای خریدهای تکرارشونده (مانند اشتراک‌های قابل تمدید خودکار)، باید شناسه تراکنش خارجی مرتبط با اولین تراکنش در خرید تکراری را به عنوان پارامتری برای هر تراکنش بعدی، از جمله بازپرداخت، ارسال کنید. این مجموعه تراکنش های آن خرید را ثبت می کند. هنگامی که محصول تغییر می کند (مانند ارتقا یا تنزل رتبه)، یا اگر تراکنش تکراری لغو یا منقضی شود و همان محصول بعداً دوباره خریداری شود، یک شناسه تراکنش خارجی جدید برای خرید ارسال می کنید. شما نباید هیچ گونه اطلاعات شناسایی شخصی، اطلاعات اختصاصی یا محرمانه را به عنوان بخشی از این شناسه تراکنش خارجی وارد کنید.

گزارش خرید جدید

هر بار که خرید جدیدی در سیستم صدور صورت‌حساب یا پیشنهادات خارجی با موفقیت انجام می‌شود، تماس با API Externaltransactions لازم است. برای این خریدهای جدید، باید یک externalTransactionId منحصر به فرد مرتبط با خرید را در باطن خود به عنوان پارامتر پرس و جو ارائه کنید. این externalTransactionId را نمی توان در شناسه بسته همان برنامه استفاده مجدد کرد.

externalTransactionToken دریافت شده توسط برنامه از طریق UserChoiceBillingListener ، AlternativeBillingOnlyReportingDetailsListener ، یا ExternalOfferReportingDetailsListener نیز به عنوان بخشی از بدنه درخواست برای خریدهای یکباره و تراکنش‌های بار اول در یک خرید تکراری (مانند اشتراک) مورد نیاز است. در هر صورت، این تراکنش اولیه نامیده می شود. پس از تراکنش اولیه، 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 دلاری داشته باشد و به دنبال آن یک تراکنش دوم در تاریخ بعد برای قیمت SKU در زمان انجام پیش‌سفارش انجام شود. برای جزئیات بیشتر در مورد گزارش معاملات بعدی، برای خرید به گزارش معاملات بعدی مراجعه کنید.

توجه: گزارش تراکنش برای خرید فقط با استفاده از صورت‌حساب جایگزین یا پیشنهادات خارجی مانند بالا است، به جز اینکه externalTransactionToken با استفاده از مراحل توضیح داده شده در راهنمای فقط صورت‌حساب جایگزین یا راهنمای پیشنهادات خارجی به دست می‌آید.

اگر تراکنش با کاربری ساکن هند که در آن مالیات متفاوت است به منطقه اداری آنها (مانند ایالت یا استان) بستگی دارد، پس حتماً آن منطقه را در 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. توسعه‌دهنده عود تراکنش را در پارامتر query 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 استفاده شده در بالا برای ایجاد تراکنش‌های تمدید را ارائه کنید. پس از انتقال اشتراک، دیگر نیازی به گزارش دستی تراکنش های بعدی برای اشتراک نخواهید داشت، مشروط بر اینکه از طریق روش های خودکار شرح داده شده در این صفحه گزارش شوند.

هنگام انتقال اشتراک‌ها، به محدودیت‌های سهمیه‌ای در محل توجه داشته باشید تا مطمئن شوید که مهاجرت باعث قطع سهمیه نمی‌شود. اگر تعداد زیادی اشتراک نیاز به انتقال دارند، آنها را در چند روز پخش کنید یا برای افزایش سهمیه درخواست کنید .

توجه: فقط برنامه‌نویسانی که صورت‌حساب جایگزین را بدون گزارش خودکار ارائه کرده‌اند، می‌توانند قسمت migratedTransactionProgram را تنظیم کنند. اگر قبلاً صورت‌حساب جایگزین را بدون اتوماسیون ارائه کرده‌اید و هنگام تلاش برای درخواست انتقال اشتراک با خطا مواجه می‌شوید، می‌توانید برای دریافت راهنمایی با تیم پشتیبانی ما تماس بگیرید .

فیلد 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 Media Experience Program شرکت می‌کنند، هنگام گزارش تراکنش‌های خارجی، باید transaction_program_code ارائه کنند. اگر یک توسعه دهنده واجد شرایط هستید، برای اطلاعات بیشتر در مورد نحوه تنظیم این فیلد، با مدیر توسعه کسب و کار خود تماس بگیرید.

بازپرداخت خرید را به Google Play گزارش دهید

برای گزارش تراکنش‌های بازپرداخت شده به کاربران خارج از سیستم صورت‌حساب Google Play، با Externaltransactions API یکپارچه شوید. برای اینکه 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 روزانه برای همه تماس‌ها است، درست مانند هر نقطه پایانی دیگر در Google Play Developer API.

علاوه بر این، API Externaltransactions دارای محدودیت 1200 Queries در دقیقه (QPM) برای تماس با Externaltransactions.createexternaltransaction یا Externaltransactions.refundexternaltransaction است. تماس با Externaltransactions.getexternaltransaction در این محدودیت 1200 QPM محاسبه نمی شود.