คู่มือการเปลี่ยนแปลงการสมัครใช้บริการในเดือนพฤษภาคม 2022

ระบบการเรียกเก็บเงินของ Google Play เป็นบริการที่เปิดโอกาสให้คุณขายผลิตภัณฑ์และเนื้อหาดิจิทัลในแอป Android เราได้เปลี่ยนแปลงวิธีกำหนดผลิตภัณฑ์ที่ต้องสมัครใช้บริการในรุ่นเดือนพฤษภาคม 2022 ซึ่งส่งผลต่อวิธีขายผลิตภัณฑ์ที่ต้องสมัครใช้บริการในแอปและวิธีจัดการในแบ็กเอนด์ หากผสานรวมกับ Google Play Billing เป็นครั้งแรก คุณสามารถเริ่มการผสานรวมได้โดยอ่านการเตรียมพร้อม

หากคุณขายการสมัครใช้บริการด้วย Google Play Billing ก่อนเดือนพฤษภาคม 2022 คุณควรทำความเข้าใจวิธีใช้ฟีเจอร์ใหม่ไปพร้อมกับการคงการสมัครใช้บริการที่มีอยู่ไว้

สิ่งแรกที่ควรทราบคือการสมัครใช้บริการ แอป และการผสานรวมแบ็กเอนด์ที่มีอยู่ทั้งหมดจะทํางานเหมือนก่อนการเปิดตัวในเดือนพฤษภาคม 2022 คุณไม่จําเป็นต้องทําการเปลี่ยนแปลงใดๆ ในทันที และสามารถใช้ฟีเจอร์ใหม่ๆ เหล่านี้ได้เมื่อเวลาผ่านไป Google Play Billing Library เวอร์ชันหลักแต่ละเวอร์ชันจะได้รับการสนับสนุนเป็นเวลา 2 ปีหลังจากการเผยแพร่ การผสานรวมที่มีอยู่กับ Google Play Developer API จะยังคงทำงานต่อไปตามปกติ

ภาพรวมของการอัปเดตเดือนพฤษภาคม 2022 มีดังนี้

• Google Play Console เวอร์ชันใหม่ให้คุณสร้างและจัดการการสมัครใช้บริการ แพ็กเกจเริ่มต้น และข้อเสนอได้ ซึ่งรวมถึงการสมัครใช้บริการใหม่และการสมัครใช้บริการที่ย้ายข้อมูล
• Play Developer API มีข้อมูลอัปเดตเพื่อรองรับฟังก์ชันการทำงานของ UI ใหม่ของ Google Play Console ในแบบฟอร์ม API สิ่งที่น่าสังเกตคือมี Subscription Purchases API เวอร์ชันใหม่ ใช้ API นี้เพื่อตรวจสอบสถานะการสมัครใช้บริการและจัดการการซื้อการสมัครใช้บริการ
• Play Billing Library เวอร์ชัน 5 เวอร์ชันใหม่นี้จะช่วยให้แอปของคุณได้รับประโยชน์จากฟีเจอร์การสมัครใช้บริการใหม่ทั้งหมด เมื่อพร้อมที่จะอัปเกรดเป็นเวอร์ชัน 5 ให้ทําตามคําแนะนําในคู่มือการย้ายข้อมูล

การกําหนดค่าการติดตาม

การจัดการการสมัครใช้บริการผ่าน Google Play Console

ในเดือนพฤษภาคม 2022 คุณจะเห็นความแตกต่างบางอย่างใน Google Play Console

ตอนนี้การสมัครใช้บริการหนึ่งๆ สามารถมีแพ็กเกจเริ่มต้นและข้อเสนอได้หลายแบบ ตอนนี้ SKU การสมัครใช้บริการที่สร้างไว้ก่อนหน้านี้จะปรากฏใน Play Console เป็นออบเจ็กต์การสมัครใช้บริการ แพ็กเกจเริ่มต้น และข้อเสนอใหม่เหล่านี้ หากยังไม่ได้อ่าน โปรดดูการเปลี่ยนแปลงล่าสุดในการสมัครใช้บริการใน Play Console เพื่อดูคำอธิบายเกี่ยวกับออบเจ็กต์ใหม่ รวมถึงฟังก์ชันการทำงานและการกําหนดค่า ผลิตภัณฑ์ที่ต้องสมัครใช้บริการทั้งหมดที่มีอยู่จะปรากฏใน Google Play Console ในรูปแบบใหม่นี้ ตอนนี้ SKU แต่ละรายการจะแสดงด้วยออบเจ็กต์การสมัครใช้บริการที่มีแพ็กเกจเริ่มต้นแพ็กเกจเดียวและข้อเสนอที่เข้ากันได้แบบย้อนหลัง (หากมี)

เนื่องจากการผสานรวมแบบเก่าคาดหวังให้การสมัครใช้บริการแต่ละรายการมีข้อเสนอเดียว ซึ่งแสดงโดยออบเจ็กต์ SkuDetails การสมัครใช้บริการแต่ละรายการจึงมีแพ็กเกจเริ่มต้นหรือข้อเสนอที่ "เข้ากันได้แบบย้อนหลัง" รายการเดียว ระบบจะแสดงแพ็กเกจเริ่มต้นหรือข้อเสนอที่เข้ากันได้แบบย้อนหลังเป็นส่วนหนึ่งของ SKU สำหรับแอปที่ใช้เมธอด querySkuDetailsAsync() ที่เลิกใช้งานแล้ว ดูข้อมูลเพิ่มเติมเกี่ยวกับการกำหนดค่าและจัดการข้อเสนอที่เข้ากันได้แบบย้อนหลังได้ที่ทำความเข้าใจการสมัครใช้บริการ เมื่อแอปของคุณใช้เฉพาะ queryProductDetailsAsync() และไม่มีแอปเวอร์ชันเก่าที่ยังคงมีการซื้อ คุณก็ไม่จําเป็นต้องใช้ข้อเสนอที่เข้ากันได้แบบย้อนหลังอีกต่อไป

การจัดการการสมัครใช้บริการผ่าน Subscriptions Publishing API

Play Developer API มีฟังก์ชันการทำงานใหม่สำหรับการซื้อการสมัครใช้บริการ API inappproducts การจัดการ SKU จะยังคงทำงานต่อไปเช่นเดิม รวมถึงจัดการผลิตภัณฑ์แบบซื้อครั้งเดียวและการสมัครใช้บริการ คุณจึงไม่จำเป็นต้องทำการเปลี่ยนแปลงใดๆ ในทันทีเพื่อรักษาการผสานรวมไว้

อย่างไรก็ตาม โปรดทราบว่า Google Play Console จะใช้เฉพาะเอนทิตีการสมัครใช้บริการแบบใหม่เท่านั้น เมื่อเริ่มแก้ไขการสมัครใช้บริการใน Console แล้ว คุณจะใช้ inappproducts API สำหรับการสมัครใช้บริการไม่ได้อีกต่อไป

หากคุณเคยใช้ Publishing API ก่อนเดือนพฤษภาคม 2022 การสมัครใช้บริการที่มีอยู่จะปรากฏเป็นอ่านอย่างเดียวใน Google Play Console เพื่อหลีกเลี่ยงปัญหา หากพยายามทำการเปลี่ยนแปลง คุณอาจได้รับคำเตือนที่อธิบายข้อจำกัดนี้ ก่อนแก้ไขการสมัครใช้บริการใน Console เพิ่มเติม คุณควรอัปเดตการผสานรวมแบ็กเอนด์เพื่อใช้ปลายทางการเผยแพร่การสมัครใช้บริการใหม่ ปลายทางใหม่ monetization.subscriptions, monetization.subscriptions.baseplans และ monetization.subscriptions.offers ช่วยให้คุณจัดการแพ็กเกจเริ่มต้นและข้อเสนอทั้งหมดที่มีได้ คุณดูการแมปช่องต่างๆ จากเอนทิตี InAppProduct ไปยังออบเจ็กต์ใหม่ในส่วน monetization.subscriptions ได้ในตารางต่อไปนี้

InAppProduct	การสมัครใช้บริการ
packageName	packageName
sku	productId
status	basePlans[0].state
prices	basePlans[0].regionalConfigs.price
listings	ข้อมูล
defaultPrice	ไม่มีความเท่าเทียม
subscriptionPeriod	basePlans[0].autoRenewingBasePlanType.billingPeriodDuration
trialPeriod	basePlans[0].offers[0].phases[0].regionalConfigs[0].free
gracePeriod	basePlans[0].autoRenewingBasePlanType.gracePeriodDuration
subscriptionTaxesAndComplianceSettings	taxAndComplianceSettings

การอัปเดต API ที่จำเป็นนี้มีผลกับ Publishing API (การจัดการ SKU) เท่านั้น

การเปลี่ยนแปลงใน Play Billing Library

Play Billing Library มีเมธอดและออบเจ็กต์ทั้งหมดที่ใช้ได้ในเวอร์ชันก่อนหน้าเพื่อรองรับการย้ายข้อมูลทีละน้อย SkuDetails ออบเจ็กต์และฟังก์ชันต่างๆ เช่น querySkuDetailsAsync() จะยังคงอยู่เพื่อให้คุณอัปเกรดเพื่อใช้ฟังก์ชันการทำงานใหม่ได้โดยไม่ต้องอัปเดตโค้ดการติดตามที่มีอยู่ในทันที นอกจากนี้ คุณยังควบคุมข้อเสนอที่พร้อมให้บริการผ่านวิธีการเหล่านี้ได้ด้วย โดยทำเครื่องหมายว่าข้อเสนอดังกล่าวใช้งานร่วมกันได้ย้อนหลัง

นอกจากการคงเมธอดเดิมไว้แล้ว ตอนนี้ Play Billing Library 5 ยังมีออบเจ็กต์ ProductDetails ใหม่และเมธอด queryProductDetailsAsync() ที่เกี่ยวข้องเพื่อจัดการเอนทิตีและฟังก์ชันการทำงานใหม่ด้วย ProductDetails รองรับไอเทมที่ซื้อในแอปที่มีอยู่ (การซื้อแบบครั้งเดียวและไอเทมที่ซื้อแล้วหมดไป) แล้ว

ProductDetails.getSubscriptionOfferDetails() จะแสดงรายการแพ็กเกจพื้นฐานและข้อเสนอทั้งหมดที่ผู้ใช้มีสิทธิ์ซื้อสำหรับการสมัครใช้บริการ ซึ่งหมายความว่าคุณจะเข้าถึงแพ็กเกจเริ่มต้นและข้อเสนอทั้งหมดที่มีสิทธิ์สำหรับผู้ใช้ได้ ไม่ว่าจะเข้ากันได้แบบย้อนหลังหรือไม่ก็ตาม getSubscriptionOfferDetails() คืน null สำหรับผลิตภัณฑ์ที่ไม่ใช่การสมัครใช้บริการ สำหรับการซื้อแบบครั้งเดียว คุณสามารถใช้ getOneTimePurchaseOfferDetails()

Play Billing Library 5 ยังมีทั้งวิธีการแบบใหม่และแบบเดิมสำหรับการเปิดใช้งานขั้นตอนการซื้อ หากออบเจ็กต์ BillingFlowParams ที่ส่งไปยัง BillingClient.launchBillingFlow() ได้รับการกําหนดค่าโดยใช้ออบเจ็กต์ SkuDetails ระบบจะดึงข้อมูลข้อเสนอที่จะขายจากแพ็กเกจเริ่มต้นหรือข้อเสนอที่เข้ากันได้แบบย้อนหลังซึ่งสอดคล้องกับ SKU หากออบเจ็กต์ BillingFlowParams ที่ส่งไปยัง BillingClient.launchBillingFlow() ได้รับการกําหนดค่าโดยใช้ออบเจ็กต์ ProductDetailsParams ซึ่งประกอบด้วย ProductDetails และ String ที่แสดงโทเค็นข้อเสนอที่เฉพาะเจาะจงสําหรับข้อเสนอที่ซื้อ ระบบจะใช้ข้อมูลดังกล่าวเพื่อระบุผลิตภัณฑ์ที่ผู้ใช้ซื้อ

queryPurchasesAsync() จะแสดงผลการซื้อทั้งหมดที่ผู้ใช้เป็นเจ้าของ หากต้องการระบุประเภทผลิตภัณฑ์ที่ขอ ให้ส่งค่า BillingClient.SkuType เช่นเดียวกับในเวอร์ชันเก่า หรือส่งออบเจ็กต์ QueryPurchasesParams ที่มีค่า BillingClient.ProductType ที่แสดงถึงเอนทิตีการสมัครใช้บริการใหม่

เราขอแนะนำให้อัปเดตแอปเป็นไลบรารีเวอร์ชัน 5 ในเร็วๆ นี้เพื่อให้คุณเริ่มใช้ประโยชน์จากฟีเจอร์การสมัครใช้บริการใหม่เหล่านี้ได้

การจัดการสถานะการสมัครใช้บริการ

ส่วนนี้จะอธิบายการเปลี่ยนแปลงหลักในคอมโพเนนต์แบ็กเอนด์ของการผสานรวมระบบการเรียกเก็บเงินของ Google Play ที่ต้องนำมาใช้งานเพื่อย้ายข้อมูลไปยังเวอร์ชัน 5

การแจ้งเตือนแบบเรียลไทม์สำหรับนักพัฒนาแอป

ในเร็วๆ นี้ออบเจ็กต์ SubscriptionNotification จะไม่มี subscriptionId อีกต่อไป หากคุณใช้ช่องนี้เพื่อระบุผลิตภัณฑ์ที่ต้องสมัครใช้บริการ คุณควรอัปเดตเพื่อรับข้อมูลจากสถานะการสมัครใช้บริการโดยใช้ purchases.subscriptionv2:get เมื่อได้รับการแจ้งเตือน องค์ประกอบ SubscriptionPurchaseLineItem แต่ละรายการในคอลเล็กชัน lineItems ที่แสดงผลเป็นส่วนหนึ่งของสถานะการซื้อจะมี productId ที่เกี่ยวข้อง

Subscriptions Purchases API: การดูสถานะการสมัครใช้บริการ

ใน Subscriptions Purchases API เวอร์ชันก่อนหน้า คุณสามารถค้นหาสถานะการสมัครใช้บริการได้โดยใช้ purchases.subscriptions:get ปลายทางนี้ไม่มีการเปลี่ยนแปลงและยังคงทํางานต่อไปสําหรับการซื้อการสมัครใช้บริการที่เข้ากันได้แบบย้อนหลัง ปลายทางนี้ไม่รองรับฟังก์ชันการทำงานใหม่ทั้งหมดที่เปิดตัวในเดือนพฤษภาคม 2022

ใน Subscriptions Purchases API เวอร์ชันใหม่ ให้ใช้ purchases.subscriptionsv2:get เพื่อดูสถานะการซื้อการสมัครใช้บริการ API นี้ใช้ได้กับการสมัครใช้บริการที่ย้ายข้อมูล การสมัครใช้บริการใหม่ (ทั้งแบบชำระเงินล่วงหน้าและแบบต่ออายุใหม่อัตโนมัติ) ตลอดจนการซื้อทุกประเภท คุณสามารถใช้ปลายทางนี้เพื่อตรวจสอบสถานะการสมัครรับข้อมูลเมื่อได้รับการแจ้งเตือน ออบเจ็กต์ SubscriptionPurchaseV2 ที่แสดงผลมีฟิลด์ใหม่ แต่ยังคงมีข้อมูลเดิมที่จําเป็นต่อการสนับสนุนการสมัครใช้บริการที่มีอยู่ต่อไป

ฟิลด์ SubscriptionPurchaseV2 สำหรับแพ็กเกจแบบชำระเงินล่วงหน้า

เราได้เพิ่มช่องใหม่เพื่อรองรับแพ็กเกจแบบชำระเงินล่วงหน้า ซึ่งผู้ใช้จะเป็นผู้ขยายเวลาแทนการต่ออายุใหม่อัตโนมัติ ฟิลด์ทั้งหมดมีผลกับแพ็กเกจแบบชำระเงินล่วงหน้าเช่นเดียวกับการสมัครใช้บริการแบบต่ออายุใหม่อัตโนมัติ โดยมีข้อยกเว้นต่อไปนี้

• [ช่องใหม่] lineItems[0].prepaid_plan.allowExtendAfterTime: ระบุเวลาที่ผู้ใช้จะได้รับอนุญาตให้ซื้อการเติมเงินอีกเพื่อขยายเวลาแพ็กเกจแบบชำระเงินล่วงหน้า เนื่องจากผู้ใช้มีสิทธิ์ใช้การเติมเงินที่ไม่ได้ใช้เพียงครั้งเดียวในแต่ละครั้ง
• [ช่องใหม่] SubscriptionState: ระบุสถานะออบเจ็กต์การสมัครใช้บริการ สำหรับแพ็กเกจแบบชำระเงินล่วงหน้า ค่านี้จะต้องเป็น ACTIVE, PENDING หรือ CANCELED เสมอ
• lineItems[0].expiryTime: ฟิลด์นี้จะแสดงสำหรับแพ็กเกจแบบชำระเงินล่วงหน้าเสมอ
• paused_state_context: ช่องนี้จะไม่มีอยู่เนื่องจากแพ็กเกจแบบชำระล่วงหน้าจะหยุดชั่วคราวไม่ได้
• lineItems[0].auto_renewing_plan: ไม่มีให้ใช้งานในแพ็กเกจแบบชำระเงินล่วงหน้า
• canceled_state_context: ไม่มีให้สำหรับแพ็กเกจแบบชำระเงินล่วงหน้า เนื่องจากช่องนี้ใช้กับผู้ใช้ที่ยกเลิกการสมัครใช้บริการอยู่เท่านั้น
• lineItems[0].productId: ช่องนี้จะแทนที่ subscriptionId จากเวอร์ชันก่อนหน้า

ฟิลด์ SubscriptionPurchaseV2 สำหรับการสมัครใช้บริการแบบตามรอบ

purchases.subscriptionv2 มีช่องใหม่ที่ให้รายละเอียดเพิ่มเติมเกี่ยวกับออบเจ็กต์การสมัครใช้บริการใหม่ ตารางต่อไปนี้แสดงวิธีที่ช่องจากปลายทางการสมัครใช้บริการเดิมแมปกับช่องที่เกี่ยวข้องใน purchases.subscriptionv2

SubscriptionPurchase	SubscriptionPurchaseV2
countryCode	regionCode
orderId	latestOrderId
(ไม่มีฟิลด์ที่เทียบเท่า)	lineItems (รายการ SubscriptionPurchaseLineItem) ที่แสดงถึงผลิตภัณฑ์ที่ซื้อ
(ไม่มีฟิลด์ที่เทียบเท่า)	lineItems.offerDetails.basePlanId
(ไม่มีฟิลด์ที่เทียบเท่า)	lineItems.offerDetails.offerId
(ไม่มีฟิลด์ที่เทียบเท่า)	lineItems.offerDetails.offerTags
startTimeMillis	startTime
expiryTimeMillis	lineItems.expiryTime (การสมัครใช้บริการแต่ละรายการที่ซื้อจะมี expiryTime ของตนเอง)
(ไม่มีฟิลด์ที่เทียบเท่า)	subscriptionState (ระบุ สถานะของการสมัครใช้บริการ)
(ไม่มีฟิลด์ที่เทียบเท่า)	pausedStateContext (แสดงเฉพาะในกรณีที่สถานะการสมัครใช้บริการเป็น SUBSCRIPTION_STATE_PAUSED)
autoResumeTimeMillis	pausedStateContext.autoResumeTime
(ไม่มีฟิลด์ที่เทียบเท่า)	canceledStateContext (แสดงเฉพาะในกรณีที่สถานะการสมัครใช้บริการเป็น SUBSCRIPTION_STATE_CANCELED)
(ไม่มีฟิลด์ที่เทียบเท่า)	testPurchase (มีเฉพาะในการซื้อของผู้ทดสอบที่ได้รับอนุญาตเท่านั้น)
autoRenewing	lineItems.autoRenewingPlan.autoRenewEnabled
priceCurrenceCode, priceAmountMicros	lineItems.autoRenewingPlan.recurringPrice
introductoryPriceInfo	(ไม่มีช่องที่เทียบเท่า) ดูข้อมูลนี้ได้ใน offer สำหรับการสมัครใช้บริการแต่ละรายการที่ซื้อ
developerPayload	(no equivalent field) เลิกใช้งานเพย์โหลดของนักพัฒนาแอปแล้ว
paymentState	(ไม่มีช่องที่เทียบเท่า) คุณสามารถอนุมานสถานะการชำระเงินจาก subscriptionState ดังนี้ การชำระเงินที่รอดำเนินการมีดังนี้ SUBSCRIPTION_STATE_PENDING (การซื้อใหม่ที่มีธุรกรรมรอดำเนินการ) SUBSCRIPTION_STATE_IN_GRACE_PERIOD SUBSCRIPTION_STATE_ON_HOLD การชำระเงินได้รับแล้วในกรณีต่อไปนี้ SUBSCRIPTION_STATE_ACTIVE ช่วงทดลองใช้ฟรี (ไม่มีฟิลด์ที่เทียบเท่า) การอัปเกรด / ดาวน์เกรดแบบเลื่อนเวลา: SUBSCRIPTION_STATE_PENDING
cancelReason, userCancellationTimeMillis, cancelSurveyResult	canceledStateContext
linkedPurchaseToken	linkedPurchaseToken (ไม่มีการเปลี่ยนแปลง)
purchaseType	ทดสอบ: ผ่าน testPurchase โปรโมชัน: signupPromotion
priceChange	lineItems.autoRenewingPlan.priceChangeDetails
profileName, emailAddress, givenName, familyName, profileId	subscribeWithGoogleInfo
acknowledgementState	acknowledgementState (no change)
promotionType, promotionCode	signupPromotion
externalAccountId, obfuscatedExternalAccountId, obfuscatedExteranlProfileId	externalAccountIdentifiers

ฟังก์ชันการจัดการการสมัครใช้บริการอื่นๆ

แม้ว่าเราจะได้อัปเกรด purchases.subscriptions:get ไปใช้ purchases.subscriptionsv2:get แล้ว แต่ฟังก์ชันการจัดการการสมัครใช้บริการของนักพัฒนาแอปอื่นๆ ยังคงเหมือนเดิมในอุปกรณ์ปลายทาง purchases.subscriptions คุณสามารถใช้งาน purchases.subscriptions:acknowledge, purchases.subscriptions:cancel, purchases.subscriptions:defer, purchases.subscriptions:refund และ purchases.subscriptions:revoke ได้ต่อไปตามปกติ

Pricing API

ใช้ปลายทาง monetization.convertRegionPrices เพื่อคำนวณราคาระดับภูมิภาคเช่นเดียวกับที่ใช้ผ่าน Play Console วิธีการนี้จะยอมรับราคาเดียวในสกุลเงินใดก็ได้ที่ Play รองรับ และจะแสดงราคาที่แปลงแล้ว (รวมถึงอัตราภาษีเริ่มต้น หากมี) สำหรับทุกภูมิภาคที่ Google Play รองรับการซื้อ