原文档链接：App Store Server Notifications 。

App Store Server Notifications

App Store Server Notifications是一项服务器到服务器的服务，当应用内购买和退款的状态发生变化时，它会实时通知您。使用通知中的数据更新您的用户帐户数据库，并监控和响应应用内购买退款。

要从 App Store 接收服务器通知，请在 App Store Connect 中提供服务器的 HTTPS URL。选择接收生产环境和沙盒环境的通知。有关更多信息，请参阅启用 Enabling App Store Server Notifications。

通知涵盖应用内购买生命周期中的事件，包括新订阅购买和续订、优惠兑换、退款等。V2 通知还支持 TEST 通知。

使用通知类型以及交易和订阅续订信息来更新用户的服务或根据您的业务逻辑提供促销优惠。

您的服务器负责解析、诠释和响应所有server-to-server的通知请求。有关更多信息，请参阅 Receiving App Store Server Notifications和Responding to App Store Server Notifications。

Enabling App Store Server Notifications

配置您的服务器并提供 HTTPS URL 以接收有关用户订阅状态更改和应用内购买退款的通知。

要从 App Store 接收服务器通知，您的服务器必须支持传输层安全性 (TLS) 1.2 协议或更高版本。

要启用 App Store 服务器通知，请按照下列步骤操作：

1. 确定服务器上用于接收生产环境通知的 HTTPS URL。

2. （可选）确定服务器上用于接收用于测试通知的沙箱环境的通知的 HTTPS URL。您可以在生产环境和沙箱环境中使用相同的 URL。

3. App Store Connect 允许您选择接收每个环境的版本 2 或版本 1 通知。如果您选择版本 2，请将您的端点设置为 App Store Server Notifications V2。如果您选择版本 1，请将您的端点设置为 App Store Server Notifications V1。

4. 在 App Store Connect 中配置您的 URL。有关更多信息，请参阅 填写 App Store 服务器通知的 URL 。

注意：如果您在 URL 中指定端口，则该端口必须为 443 或大于或等于 1024。例如，URL example.com:1234/notifications 指定端口 1234。

如果您的服务器要求 IP 地址位于允许列表中，请添加 IP 地址子网 17.0.0.0/8，以允许您的服务器接收来自 App Store 服务器的通知。该子网适用于沙箱和生产环境。

Receiving App Store Server Notifications

App Store 使用 HTTP POST 将 JSON 对象传送到您的服务器，以记录值得注意的应用内购买事件。您的服务器负责解析、诠释和响应所有服务器到服务器的通知请求。有关响应的更多信息，请参阅 Responding to App Store Server Notifications 。

POST 的正文包含版本 2 通知的 responseBodyV2 和版本 1 的 responseBodyV1 中描述的数据元素。根据以下信息解析它们：

• V2 响应正文 responseBodyV2 包含一个由 App Store 以 JSON Web Signature (JWS) 格式加密签名的 signedPayload。JWS 格式提高了安全性，并使您能够在服务器上解码和验证签名。通知数据包含 App Store 在 JWS 中签名的交易和订阅续订信息。App Store Server API 和 StoreKit In-App Purchase API 对交易和订阅状态信息使用相同的 JWS 签名格式。有关 JWS 的更多信息，请参阅 IETF RFC 7515 规范。

• V1 响应正文 responseBodyV1 是一个 JSON 对象。它包括包含应用程序最近的应用内购买交易的收据。有关更多信息，请参阅 unified_receipt 对象。

使用通知类型以及交易和订阅续订信息来更新用户的服务或根据您的业务逻辑提供促销优惠。

Responding to App Store Server Notifications

发送 HTTP 状态代码以指示通知请求成功。

当您在服务器上设置端点以接收通知时，请为您的服务器配置发送响应。使用 HTTP 状态代码指示 App Store 服务器通知请求是否成功。如果请求成功，则发送 HTTP 200。如果请求失败，请发送 HTTP 50x 或 40x 让 App Store 重试通知。您的服务器不需要返回数据值。

如果 App Store 服务器在初次通知尝试后没有收到来自您的服务器的 200 响应，则会按如下方式重试：

• 对于 V1 通知，它会在上次尝试后的 6、24 和 48 小时重试 3 次。

• 对于 V2 通知，它会在上次尝试后的 1、12、24、48 和 72 小时重试五次。

注意：重试通知仅在生产环境中可用。在沙盒环境中，App Store 服务器会尝试发送一次通知。

如果您的服务器由于中断而错过通知，您始终可以通过调用 App Store Server API 端点中的 Get Transaction History 和 Get All Subscription Statuses 来获取最新交易信息。

如果您使用 V2 通知（App Store Server Notifications V2），您可以通过调用 Get Notification History 来恢复错过的通知。您还可以通过调用 Request a Test Notification 端点来测试您的服务器是否正在正确接收和响应 V2 通知。

App Store Server Notifications V2

在 App Store Connect 中指定您的安全服务器的 URL 以接收 V2 通知。

要从 App Store 接收服务器通知，请在 App Store Connect 中提供安全服务器的 HTTPS URL。有关更多信息，请参阅Enabling App Store Server Notifications。

收到服务器通知后，如果发布成功，则使用 HTTP 状态代码 200 响应 App Store。如果发布不成功，请发送 HTTP 50x 或 40x 让 App Store 重试通知。有关更多信息，请参阅 Responding to App Store Server Notifications。

responseBodyV2

App Store 发送的服务器通知V2版本的响应内容。

object

signedPayload 对象为 JWS 表现。要从通知载荷(payload)中获取交易和订阅续订详细信息，请按如下方式处理signedPayload：

1. 解析signedPayload 以识别JWS 头部(header)、载荷(payload)和签名(signature)。

2. 对载荷(payload)进行 Base64 URL 解码以获得 responseBodyV2DecodedPayload。解码后的载荷(payload)包含 notificationType 、 subtype、其他通知元数据以及 data 对象或 summary 对象。

3. 该data对象包含一个signedTransactionInfo (JWSTransaction 和一个signedRenewalInfo (JWSRenewalInfo)，具体取决于通知类型。对这些签名的 JWS 表现进行解析和 Base64 URL 解码，以获取交易和订阅续订详细信息。

每个签名的 JWS 表现、signedPayload、signedTransactionInfo 和signedRenewalInfo 都具有可以在您的服务器上验证的 JWS 签名。使用头部(header)的 alg 参数中指定的算法来验证签名。有关验证签名的更多信息，请参阅 JSON Web Signature (JWS) IETF RFC 7515 规范。

signedPayload

采用 JSON Web Signature (JWS) 格式的加密签名载荷，包含 V2 通知的响应正文。

string

signedPayload 是由三个 Base64 URL 编码组件组成的字符串，以句点分隔。该字符串包含通知响应正文的 JWS 表示形式，由 App Store 根据 JSON Web Signature (JWS) IETF RFC 7515 规范进行签名。

字符串的三个组成部分依次是头部(header)、载荷(payload)和签名(signature)。

要读取通知响应正文，请对载荷(payload)进行 Base64 URL 解码。使用 responseBodyV2DecodedPayload对象读取有效负载信息。

要读取头部(header)，请对其进行 Base64 URL 解码并使用 JWSDecodedHeader 对象来访问信息。使用解码后的头部(header)中的信息来验证签名(signature)。

responseBodyV2DecodedPayload

包含 V2 通知数据的已解码载荷(payload)。

object

解码后的载荷(payload)包含有关通知的信息。使用 notificationType 和subtype来了解此通知的事件。 data对象包含详细信息，包括环境、应用程序元数据以及签名的交易和订阅续订信息。

仅当 notificationType 为 RENEWAL_EXTENSION 且 subtype 值为 SUMMARY 时， summary对象才包含信息。有关详细信息，请参阅 延长所有活跃订阅者的订阅续订日期。

notificationType

描述 App Store 发送 V2 通知的应用内购买事件的类型。

string

Possible Values

• CONSUMPTION_REQUEST

  A notification type that indicates that the customer initiated a refund request for a consumable in-app purchase, and the App Store is requesting that you provide consumption data. For more information, see Send Consumption Information.

  一种通知类型，表明客户发起了应用内消费品购买的退款请求，并且 App Store 要求您提供消费数据。 有关更多信息，请参见发送消费信息。

• DID_CHANGE_RENEWAL_PREF

  A notification type that, along with its subtype, indicates that the user made a change to their subscription plan. If the subtype is UPGRADE, the user upgraded their subscription, or cross-graded to a subscription with the same duration. The upgrade goes into effect immediately, starting a new billing period, and the user receives a prorated refund for the unused portion of the previous period. If the subtype is DOWNGRADE, the user downgraded their subscription or cross-graded to a subscription with a different duration. Downgrades take effect at the next renewal date and don’t affect the currently active plan.If the subtype is empty, the user changed their renewal preference back to the current subscription, effectively canceling a downgrade.For more information on subscription levels, see Ranking subscriptions within the group.

  一种通知类型，及其subtype表示用户对其订阅计划进行了更改。

  如果subtype是UPGRADE，则用户升级其订阅，或交叉分级为具有相同持续时间的订阅。 升级立即生效，开始新的计费周期，用户将收到上一周期未使用部分的按比例退款。

  如果subtype是DOWNGRADE，则用户降级其订阅或交叉分级为具有不同持续时间的订阅。 降级将在下一个续订日期生效，并且不会影响当前有效的计划。

  如果subtype为空，则用户将其续订首选项更改回当前订阅，从而有效地取消降级。 请参阅组内订阅排名。

• DID_CHANGE_RENEWAL_STATUS

  A notification type that, along with its subtype, indicates that the user made a change to the subscription renewal status. If the subtype is AUTO_RENEW_ENABLED, the user reenabled subscription auto-renewal. If the subtype is AUTO_RENEW_DISABLED, the user disabled subscription auto-renewal, or the App Store disabled subscription auto-renewal after the user requested a refund.

  一种通知类型，及其subtype表示用户对订阅更新续订状态进行了更改。

  如果subtype为AUTO_RENEW_ENABLED，则用户重新启用订阅自动续订。

  如果subtype为AUTO_RENEW_DISABLED，则用户禁用了订阅自动续订，或者用户申请退款后App Store禁用了订阅自动续费。

• DID_FAIL_TO_RENEW

  A notification type that, along with its subtype, indicates that the subscription failed to renew due to a billing issue. The subscription enters the billing retry period. If the subtype is GRACE_PERIOD, continue to provide service through the grace period. If the subtype is empty, the subscription isn’t in a grace period and you can stop providing the subscription service.Inform the user that there may be an issue with their billing information. The App Store continues to retry billing for 60 days, or until the user resolves their billing issue or cancels their subscription, whichever comes first. For more information, see Reducing Involuntary Subscriber Churn.

  通知类型，及其subtype表示订阅由于计费问题而未能续订。 订阅进入计费重试期。

  如果subtype为GRACE_PERIOD，请在整个宽限期继续提供服务。

  如果subtype为空，则订阅不在宽限期，您可以停止提供订阅服务。

  向用户介绍其计费信息可能存在问题。 App Store继续重试60天，或直到用户解决其计费问题或取消其订阅，以先到者为准。 For more information, see Reducing Involuntary Subscriber Churn.

• DID_RENEW

  A notification type that, along with its subtype, indicates that the subscription successfully renewed. If the subtype is BILLING_RECOVERY, the expired subscription that previously failed to renew has successfully renewed. If the substate is empty, the active subscription has successfully auto-renewed for a new transaction period. Provide the customer with access to the subscription’s content or service.

  通知类型，及其subtype表示订阅成功续订。

  如果subtype是BILLING_RECOVERY，则先前未能续订的过期订阅已成功续订。

  如果subtype为空，则活动订阅已成功自动续订新的交易周期。 为客户提供订阅内容或服务的访问。

• EXPIRED

  A notification type that, along with its subtype, indicates that a subscription expired. If the subtype is VOLUNTARY, the subscription expired after the user disabled subscription renewal. If the subtype is BILLING_RETRY, the subscription expired because the billing retry period ended without a successful billing transaction. If the subtype is PRICE_INCREASE, the subscription expired because the user didn’t consent to a price increase that requires user consent. If the subtype is PRODUCT_NOT_FOR_SALE, the subscription expired because the product wasn’t available for purchase at the time the subscription attempted to renew. A notification without a subtype indicates that the subscription expired for some other reason.

  通知类型，及其subtype表示订阅已过期。

  如果subtype是VOLUNTARY，则在用户禁用订阅续订后订阅过期。

  如果subtype是BILLING_RETRY，则订阅到期，因为计费重试期结束而没有成功的计费交易。

  如果subtype为PRICE_INCREASE，则订阅过期，因为用户未同意需要用户同意的价格上涨。

  如果subtype为PRODUCT_NOT_FOR_SALE，则订阅过期，因为在订阅试图续订时无法购买产品。

  没有subtype的通知表明订阅出于某些其他原因而过期。

• GRACE_PERIOD_EXPIRED

  A notification type that indicates that the billing grace period has ended without renewing the subscription, so you can turn off access to the service or content. Inform the user that there may be an issue with their billing information. The App Store continues to retry billing for 60 days, or until the user resolves their billing issue or cancels their subscription, whichever comes first. For more information, see Reducing Involuntary Subscriber Churn.

  通知类型，表明计费宽限期已经结束而不续订订阅，因此您可以关闭对服务或内容的访问。 通知用户他们的计费信息可能存在问题。 App Store继续重试60天，或直到用户解决其计费问题或取消其订阅，以先到者为准。 For more information, see Reducing Involuntary Subscriber Churn.

• OFFER_REDEEMED

  A notification type that, along with its subtype, indicates that the user redeemed a promotional offer or offer code.

  If the subtype is INITIAL_BUY, the user redeemed the offer for a first-time purchase. If the subtype is RESUBSCRIBE, the user redeemed an offer to resubscribe to an inactive subscription. If the subtype is UPGRADE, the user redeemed an offer to upgrade their active subscription, which goes into effect immediately. If the subtype is DOWNGRADE, the user redeemed an offer to downgrade their active subscription, which goes into effect at the next renewal date. If the user redeemed an offer for their active subscription, you receive an OFFER_REDEEMED notification type without a subtype. For more information about promotional offers, see Implementing promotional offers in your app. For more information about offer codes, see Implementing offer codes in your app.

  通知类型，及其subtype，表示用户兑换了促销优惠或优惠代码。

  如果subtype为INITIAL_BUY，则用户兑换了首次购买的优惠。

  如果subtype为RESUBSCRIBE，则用户兑换了要重新订阅非活动订阅的优惠。

  如果subtype是UPGRADE，则用户兑换了升级其活动订阅的优惠，该优惠立即生效。

  如果subtype为DOWNGRADE，则用户兑换了降级其有效订阅的优惠，该优惠将在下一个续订日期生效。

  如果用户兑换了其有效订阅的优惠，您将收到不带subtype的 OFFER_REDEEMED 通知类型。

  有关促销优惠的更多信息，请参见在您的应用程序中实施促销优惠。 有关报价代码的更多信息，请参见在您的应用程序中实施优惠代码。

• PRICE_INCREASE

  A notification type that, along with its subtype, indicates that the system has informed the user of an auto-renewable subscription price increase. If the price increase requires user consent, the subtype is PENDING if the user hasn’t responded to the price increase, or ACCEPTED if the user has consented to the price increase. If the price increase doesn’t require user consent, the subtype is ACCEPTED.For information about how the system calls your app before it displays the price consent sheet for subscription price increases that require customer consent, see paymentQueueShouldShowPriceConsent(_:). For information about managing subscription prices, see Managing Price Increases for Auto-Renewable Subscriptions and Managing Prices.

  通知类型，及其subtype，表明系统已通知用户自动续订订阅价格上涨。

  如果涨价需要用户同意，则如果用户未响应涨价，则subtype为PENDING；如果用户同意涨价，则subtype为ACCEPTED。

  如果价格上涨不需要用户同意 ，则subtype是Accepted。

  有关系统如何在显示需要客户同意的订阅价格上涨的价格同意表之前调用您的应用的信息，请参阅 paymentQueueShouldShowPriceConsent(_:)。有关管理订阅价格的信息，请参阅管理自动续订订阅的价格上涨和管理价格。

• REFUND

  A notification type that indicates that the App Store successfully refunded a transaction for a consumable in-app purchase, a non-consumable in-app purchase, an auto-renewable subscription, or a non-renewing subscription. The revocationDate contains the timestamp of the refunded transaction. The originalTransactionId and productId identify the original transaction and product. The revocationReason contains the reason. To request a list of all refunded transactions for a user, see Get Refund History in the App Store Server API.

  一种通知类型，指示 App Store 已成功对消费品应用内购买、非消费品应用内购买、自动续订订阅或非续订订阅的交易进行退款。reservationDate 包含退款交易的时间戳。 OriginalTransactionId和 ProductId 标识原始交易和产品。 reservationReason包含原因。要请求用户的所有退款交易列表，请参阅 App Store Server API 中的获取退款历史记录。

• REFUND_DECLINED

  A notification type that indicates the App Store declined a refund request initiated by the app developer using any of the following methods: beginRefundRequest(for:in：), beginRefundRequest(in：), beginRefundRequest(for:in：), beginRefundRequest(in：), and refundRequestSheet(for：isPresented：onDismiss：).

一种通知类型，指示 App Store 拒绝了应用开发者使用以下任一方法发起的退款请求： beginRefundRequest(for:in：), beginRefundRequest(in：), beginRefundRequest(for:in：), beginRefundRequest(in：), 和 refundRequestSheet(for：isPresented：onDismiss：).

• REFUND_REVERSED

  A notification type that indicates the App Store reversed a previously granted refund due to a dispute that the customer raised. If your app revoked content or services as a result of the related refund, it needs to reinstate them. This notification type can apply to any in-app purchase type: consumable, non-consumable, non-renewing subscription, and auto-renewable subscription. For auto-renewable subscriptions, the renewal date remains unchanged when the App Store reverses a refund.

  一种通知类型，表明 App Store 由于客户提出的争议而撤销了之前授予的退款。如果您的应用因相关退款而撤销了内容或服务，则需要恢复它们。此通知类型可适用于任何应用内购买类型：消耗型、非消耗型、非续订订阅和自动续订订阅。 对于自动续订订阅，当 App Store 撤销退款时，续订日期保持不变。

• RENEWAL_EXTENDED

  A notification type that indicates the App Store extended the subscription renewal date for a specific subscription. You request subscription-renewal-date extensions by calling Extend a Subscription Renewal Date or Extend Subscription Renewal Dates for All Active Subscribers in the App Store Server API.

  一种通知类型，指示 App Store 延长了特定订阅的订阅续订日期。 您可以通过调用 App Store Server API 中的 延长订阅续订日期 或 为所有活跃订阅者延长订阅续订日期 来请求订阅续订日期延期。

• RENEWAL_EXTENSION

  A notification type that, along with its subtype, indicates that the App Store is attempting to extend the subscription renewal date that you request by calling Extend Subscription Renewal Dates for All Active Subscribers.If the subtype is SUMMARY, the App Store completed extending the renewal date for all eligible subscribers. See the summary in the responseBodyV2DecodedPayload for details. If the subtype is FAILURE, the renewal date extension didn’t succeed for a specific subscription. See the data in the responseBodyV2DecodedPayload for details.

  一种通知类型及其subtype型，表明 App Store 正在尝试延长订阅续订日期，因为您调用了 延长所有活跃订阅者的订阅续订日期 。

  如果subtype为SUMMARY，则 App Store 已完成为所有符合条件的订阅者延长续订日期。有关详细信息，请参阅responseBodyV2DecodedPayload 中的摘要。

  如果subtype为 FAILURE，则特定订阅的续订日期延期未成功。详情请参见responseBodyV2DecodedPayload中的数据。

• REVOKE

  A notification type that indicates that an in-app purchase the user was entitled to through Family Sharing is no longer available through sharing. The App Store sends this notification when a purchaser disabled Family Sharing for a product, the purchaser (or family member) left the family group, or the purchaser asked for and received a refund. Your app also receives a paymentQueue(_:didRevokeEntitlementsForProductIdentifiers：) call. Family Sharing applies to non-consumable in-app purchases and auto-renewable subscriptions. For more information about Family Sharing, see Supporting Family Sharing in your app.

  一种通知类型，表明用户有权通过家庭共享获得的应用内购买，不再通过共享获得。当购买者禁用产品的家庭共享、购买者（或家庭成员）离开家庭群组或者购买者要求并收到退款时，App Store 会发送此通知。您的应用程序还会收到 paymentQueue(_:didRevokeEntitlementsForProductIdentifiers：) 调用。家庭共享适用于非消耗性应用内购买和自动续订订阅。 有关家庭共享的更多信息，请参见支持您的应用程序中的家庭共享。

• SUBSCRIBED

  A notification type that, along with its subtype, indicates that the user subscribed to a product. If the subtype is INITIAL_BUY, the user either purchased or received access through Family Sharing to the subscription for the first time. If the subtype is RESUBSCRIBE, the user resubscribed or received access through Family Sharing to the same subscription or to another subscription within the same subscription group.

  通知类型，及其subtype表示用户订阅了产品。

  如果subtype为 INITIAL_BUY，则用户首次通过家人共享购买或接收了对订阅的访问权限。

  如果subtype是 RESUBSCRIBE，则用户通过家人共享重新订阅或接收对同一订阅或同一订阅组内的另一个订阅的访问权限。

• TEST

  A notification type that the App Store server sends when you request it by calling the Request a Test Notification endpoint. Call that endpoint to test whether your server is receiving notifications. You receive this notification only at your request. For troubleshooting information, see the Get Test Notification Status endpoint.

  当您通过调用 Request a Test Notification 时，App Store Server发送的通知类型。 调用该端点来测试您的服务器是否正在接收通知。仅当您提出请求时，您才会收到此通知。 有关故障排除信息，请参见 Get Test Notification Status endpoint。

subtype

string

responseBodyV2DecodedPayload的一部分，并进一步描述notificationType类型的事件。它仅针对特定 V2 通知出现。

具体参考notificationType部分。

data

object

应用程序元数据以及签名的续订和交易信息。

JWSRenewalInfo

由 App Store 签名的订阅续订信息，采用 JSON Web Signature (JWS) 格式。

string

解析方法同 signedPayload，解析为 JWSRenewalInfoDecodedPayload 对象。

JWSRenewalInfoDecodedPayload

包含自动续订订阅的订阅续订信息的解码载荷(payload)。

object

JWSTransaction

由 App Store 签名的交易信息，采用 JSON Web Signature (JWS) 格式。

string

解析方法同 signedPayload，解析为 JWSTransactionDecodedPayload 对象。

JWSTransactionDecodedPayload

包含交易信息的已解码载荷(payload)。

object

summary

订阅续订日期延期通知的有效负载数据。

object

JWSDecodedHeader

包含交易或续订信息的已解码 JSON Web Signature 标头(header)。

object

所有 JWS 表现（包括signedPayload）都包含 JWS 标头（Header）。当您对标头进行 Base64 URL 解码时，请使用 JWSDecodedHeader 对象读取其内容。使用 JWSDecodedHeader 中的信息来验证 JWS 签名。有关验证签名的更多信息，请参阅 JSON Web Signature (JWS) IETF RFC 7515 规范。

App Store 对您在 App Store Server Notifications V2 和 App Store Server API 中收到的交易和续订信息进行签名。它按顺序使用以下 x5c 证书链：

1. 包含公钥的证书，该公钥与 App Store 用于对 JWS 进行数字签名的密钥相对应。第 4.11.10 节“Apple Inc. 证书实践声明全球开发者关系文件的 Mac App Store 收据签名证书”定义了此证书的策略。 Apple Inc. Certificate Practice Statement Worldwide Developer Relations 文件的 第 4.11.10 节 “Mac App Store 收据签名证书” 定义了此证书的策略。

2. 来自 Apple PKI 站点的 Apple 中间证书，以Worldwide Developer Relations开头。

3. Apple 根证书。

有关更多信息，或下载 Apple 的根证书和中间证书，请参阅 Apple PKI 。

本作品采用《CC 协议》，转载必须注明作者和本文链接