Skip to content

Commit 334faff

Browse files
authored
[in_app_purchase] Support StoreKit 2 introductory offer eligibility JWS (flutter#12584)
Adds an optional StoreKit 2-specific field to `Sk2PurchaseParam` that forwards a server-signed compact JWS to [`Product.PurchaseOption.introductoryOfferEligibility(compactJWS:)`](https://developer.apple.com/documentation/storekit/product/purchaseoption/introductoryoffereligibility(compactjws:)). Fixes flutter#191668 ## Problem StoreKit 2 lets an app's own server decide, per purchase, whether an introductory offer applies. The app receives a compact JWS signed with an App Store Connect In-App Purchase key ([Generating JWS to sign App Store requests](https://developer.apple.com/documentation/storekit/generating-jws-to-sign-app-store-requests)) whose `allowIntroductoryOffer` claim Apple documents as "a Boolean value, `true` or `false`, that determines whether the customer is eligible for an introductory offer". The plugin did not expose this purchase option, so apps whose eligibility rules live on their own server could not use the plugin's purchase path. This is distinct from the existing `isIntroductoryOfferEligible(productId)`, which wraps `Product.SubscriptionInfo.isEligibleForIntroOffer` and **reads** the App Store's *default* eligibility. That read cannot express a server-signed per-purchase decision. ## Implementation ```dart Sk2PurchaseParam( productDetails: productDetails, introductoryOfferEligibilityCompactJWS: compactJWSFromMyServer, ); ``` The value flows through `SK2ProductPurchaseOptions` and the Pigeon message to the Swift purchase-option builder: ```swift if let compactJWS = options?.introductoryOfferEligibilityCompactJWS { purchaseOptions.insert(.introductoryOfferEligibility(compactJWS: compactJWS)) } ``` The JWS is opaque to the plugin: it is never generated, signed, parsed, validated or inspected. Generated Pigeon files were regenerated with the repository's canonical `dart run pigeon --input pigeons/sk2_pigeon.dart`. ## Availability No `#available` gate is required. `introductoryOfferEligibility(compactJWS:)` is declared `@backDeployed(before: iOS 18.4, macOS 15.4, tvOS 18.4, watchOS 11.4, visionOS 2.4)` with availability iOS 15.0+ / macOS 12.0+, which is the same floor as the existing `@available(iOS 15.0, macOS 12.0, *)` StoreKit 2 extension it is added to. ## Backwards compatibility Not breaking: - the field is optional and null by default - when null, no purchase option is added and the App Store applies its own default eligibility, so existing apps behave identically - the new Pigeon field is appended, so existing encoded payloads decode unchanged - StoreKit 1 is untouched - `isIntroductoryOfferEligible`, promotional offers, win-back offers, `appAccountToken` and `quantity` are unchanged and continue to work alongside the new option ## Tests Dart (`in_app_purchase_storekit_2_platform_test.dart`), all passing: - null JWS -> no option is sent - non-null JWS -> forwarded unchanged - JWS coexists with `appAccountToken`, `quantity`, `promotionalOffer` and `winBackOfferId` - a generic `PurchaseParam` sends no JWS Native (`InAppPurchaseStoreKit2PluginTests.swift`): - `testPurchaseWithIntroductoryOfferEligibilityJWS` drives a purchase with the option set and passes. ## Known limitation in local native verification I could not run the full `RunnerTests` suite locally. It crashes in `StoreKit2TranslatorTests.setUp()` (`StoreKit2TranslatorTests.swift:69`) with `EXC_BREAKPOINT`/`SIGTRAP`, and the existing purchase-success tests fail with `PigeonError` plus an asynchronous timeout. This is independent of this change: I reproduced the identical crash signature and the identical purchase-test failure on the unmodified upstream base (9f595f3) under the same Xcode 26.6 / iOS 26.5 simulator. It matches flutter#184678, including the same file and line and the same `SKTestSession` `SKInternalErrorDomain Code=3` symptom. To be precise about what was verified locally: the patch-specific native test passes, and `dart format`, `flutter analyze`, the 106 Dart unit tests and `swift-format lint --strict` are all clean. I am **not** claiming the full native suite passes. Because product lookup fails in that environment, the native test exercises the call path but cannot by itself assert the option reached StoreKit; the deterministic assertions for that are the Dart tests above, and the Swift call site was additionally verified with `swiftc -typecheck` against the iOS 15 target. No unrelated upstream test was modified or worked around. ## Pre-Review Checklist [^1]: See "Known limitation in local native verification" above regarding the pre-existing native suite failure tracked in flutter#184678.
1 parent e941cd1 commit 334faff

11 files changed

Lines changed: 194 additions & 6 deletions

File tree

‎packages/in_app_purchase/in_app_purchase_storekit/CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,10 @@
1+
## 0.4.12
2+
3+
* Adds support for setting introductory offer eligibility from a server-signed
4+
compact JWS via `Sk2PurchaseParam.introductoryOfferEligibilityCompactJWS`,
5+
which is forwarded to StoreKit 2 as
6+
`Product.PurchaseOption.introductoryOfferEligibility(compactJWS:)`.
7+
18
## 0.4.11+2
29

310
* Updates pigeon dev_dependency to ^27.3.2 for analyzer 14 compatibility.

‎packages/in_app_purchase/in_app_purchase_storekit/darwin/in_app_purchase_storekit/Sources/in_app_purchase_storekit/StoreKit2/InAppPurchasePlugin+StoreKit2.swift‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,13 @@ extension InAppPurchasePlugin: InAppPurchase2API {
8585
}
8686
}
8787

88+
// No availability check is needed: `introductoryOfferEligibility` is
89+
// back deployed, so it is available on the same iOS 15 / macOS 12
90+
// floor as the rest of this StoreKit 2 extension.
91+
if let compactJWS = options?.introductoryOfferEligibilityCompactJWS {
92+
purchaseOptions.insert(.introductoryOfferEligibility(compactJWS: compactJWS))
93+
}
94+
8895
for await verificationResult in Transaction.unfinished {
8996
switch verificationResult {
9097
case .verified(let transaction):

‎packages/in_app_purchase/in_app_purchase_storekit/darwin/in_app_purchase_storekit/Sources/in_app_purchase_storekit/StoreKit2/StoreKit2Messages.g.swift‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -640,19 +640,27 @@ struct SK2ProductPurchaseOptionsMessage: Hashable, CustomStringConvertible {
640640
var quantity: Int64? = nil
641641
var promotionalOffer: SK2SubscriptionOfferPurchaseMessage? = nil
642642
var winBackOfferId: String? = nil
643+
/// A compact JWS, signed by the developer's server, that sets the customer's
644+
/// eligibility for an introductory offer on this purchase.
645+
///
646+
/// This is passed to StoreKit verbatim; it is never parsed or validated
647+
/// client-side.
648+
var introductoryOfferEligibilityCompactJWS: String? = nil
643649

644650
// swift-format-ignore: AlwaysUseLowerCamelCase
645651
static func fromList(_ pigeonVar_list: [Any?]) -> SK2ProductPurchaseOptionsMessage? {
646652
let appAccountToken: String? = nilOrValue(pigeonVar_list[0])
647653
let quantity: Int64? = nilOrValue(pigeonVar_list[1])
648654
let promotionalOffer: SK2SubscriptionOfferPurchaseMessage? = nilOrValue(pigeonVar_list[2])
649655
let winBackOfferId: String? = nilOrValue(pigeonVar_list[3])
656+
let introductoryOfferEligibilityCompactJWS: String? = nilOrValue(pigeonVar_list[4])
650657

651658
return SK2ProductPurchaseOptionsMessage(
652659
appAccountToken: appAccountToken,
653660
quantity: quantity,
654661
promotionalOffer: promotionalOffer,
655-
winBackOfferId: winBackOfferId
662+
winBackOfferId: winBackOfferId,
663+
introductoryOfferEligibilityCompactJWS: introductoryOfferEligibilityCompactJWS
656664
)
657665
}
658666
func toList() -> [Any?] {
@@ -661,6 +669,7 @@ struct SK2ProductPurchaseOptionsMessage: Hashable, CustomStringConvertible {
661669
quantity,
662670
promotionalOffer,
663671
winBackOfferId,
672+
introductoryOfferEligibilityCompactJWS,
664673
]
665674
}
666675
static func == (lhs: SK2ProductPurchaseOptionsMessage, rhs: SK2ProductPurchaseOptionsMessage)
@@ -673,6 +682,8 @@ struct SK2ProductPurchaseOptionsMessage: Hashable, CustomStringConvertible {
673682
&& StoreKit2MessagesPigeonInternal.deepEquals(lhs.quantity, rhs.quantity)
674683
&& StoreKit2MessagesPigeonInternal.deepEquals(lhs.promotionalOffer, rhs.promotionalOffer)
675684
&& StoreKit2MessagesPigeonInternal.deepEquals(lhs.winBackOfferId, rhs.winBackOfferId)
685+
&& StoreKit2MessagesPigeonInternal.deepEquals(
686+
lhs.introductoryOfferEligibilityCompactJWS, rhs.introductoryOfferEligibilityCompactJWS)
676687
}
677688

678689
func hash(into hasher: inout Hasher) {
@@ -681,11 +692,13 @@ struct SK2ProductPurchaseOptionsMessage: Hashable, CustomStringConvertible {
681692
StoreKit2MessagesPigeonInternal.deepHash(value: quantity, hasher: &hasher)
682693
StoreKit2MessagesPigeonInternal.deepHash(value: promotionalOffer, hasher: &hasher)
683694
StoreKit2MessagesPigeonInternal.deepHash(value: winBackOfferId, hasher: &hasher)
695+
StoreKit2MessagesPigeonInternal.deepHash(
696+
value: introductoryOfferEligibilityCompactJWS, hasher: &hasher)
684697
}
685698

686699
public var description: String {
687700
return
688-
"SK2ProductPurchaseOptionsMessage(appAccountToken: \(String(describing: appAccountToken)), quantity: \(String(describing: quantity)), promotionalOffer: \(String(describing: promotionalOffer)), winBackOfferId: \(String(describing: winBackOfferId)))"
701+
"SK2ProductPurchaseOptionsMessage(appAccountToken: \(String(describing: appAccountToken)), quantity: \(String(describing: quantity)), promotionalOffer: \(String(describing: promotionalOffer)), winBackOfferId: \(String(describing: winBackOfferId)), introductoryOfferEligibilityCompactJWS: \(String(describing: introductoryOfferEligibilityCompactJWS)))"
689702
}
690703
}
691704

‎packages/in_app_purchase/in_app_purchase_storekit/example/shared/RunnerTests/InAppPurchaseStoreKit2PluginTests.swift‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -389,6 +389,26 @@ final class InAppPurchase2PluginTests: XCTestCase {
389389
await fulfillment(of: [expectation], timeout: 5)
390390
}
391391

392+
func testPurchaseWithIntroductoryOfferEligibilityJWS() async throws {
393+
let expectation = self.expectation(
394+
description: "Purchase with an introductory offer eligibility JWS should complete")
395+
396+
// The plugin forwards this compact JWS to StoreKit verbatim, without
397+
// parsing or validating it. The purchase is driven end to end to exercise
398+
// that path; the callback is not asserted on a specific outcome because a
399+
// locally generated JWS is not signed by App Store Connect.
400+
let compactJWS = "eyJhbGciOiJFUzI1NiJ9.eyJhdWQiOiJ0ZXN0In0.c2ln"
401+
let options = SK2ProductPurchaseOptionsMessage(
402+
appAccountToken: nil, promotionalOffer: nil, winBackOfferId: nil,
403+
introductoryOfferEligibilityCompactJWS: compactJWS)
404+
405+
plugin.purchase(id: "subscription_silver", options: options) { _ in
406+
expectation.fulfill()
407+
}
408+
409+
await fulfillment(of: [expectation], timeout: 5)
410+
}
411+
392412
func testRestoreProductSuccess() async throws {
393413
let purchaseExpectation = self.expectation(description: "Purchase request should succeed")
394414
let restoreExpectation = self.expectation(description: "Restore request should succeed")

‎packages/in_app_purchase/in_app_purchase_storekit/lib/src/in_app_purchase_storekit_platform.dart‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,8 @@ class InAppPurchaseStoreKitPlatform extends InAppPurchasePlatform {
108108
/// - [Sk2PurchaseParam] — to include StoreKit2-specific fields like:
109109
/// - [winBackOfferId]: Applies a win-back offer.
110110
/// - [promotionalOffer]: Applies a promotional offer (requires a valid signature).
111+
/// - [introductoryOfferEligibilityCompactJWS]: Sets introductory offer
112+
/// eligibility from a server-signed compact JWS.
111113
///
112114
/// - [AppStorePurchaseParam] — for StoreKit1 flows using `SKPaymentQueue`.
113115
///
@@ -163,6 +165,8 @@ class InAppPurchaseStoreKitPlatform extends InAppPurchasePlatform {
163165
quantity: purchaseParam.quantity,
164166
winBackOfferId: purchaseParam.winBackOfferId,
165167
promotionalOffer: _convertPromotionalOffer(purchaseParam.promotionalOffer),
168+
introductoryOfferEligibilityCompactJWS:
169+
purchaseParam.introductoryOfferEligibilityCompactJWS,
166170
);
167171
} else {
168172
options = SK2ProductPurchaseOptions(

‎packages/in_app_purchase/in_app_purchase_storekit/lib/src/sk2_pigeon.g.dart‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -579,6 +579,7 @@ class SK2ProductPurchaseOptionsMessage {
579579
this.quantity = 1,
580580
this.promotionalOffer,
581581
this.winBackOfferId,
582+
this.introductoryOfferEligibilityCompactJWS,
582583
});
583584

584585
String? appAccountToken;
@@ -589,8 +590,21 @@ class SK2ProductPurchaseOptionsMessage {
589590

590591
String? winBackOfferId;
591592

593+
/// A compact JWS, signed by the developer's server, that sets the customer's
594+
/// eligibility for an introductory offer on this purchase.
595+
///
596+
/// This is passed to StoreKit verbatim; it is never parsed or validated
597+
/// client-side.
598+
String? introductoryOfferEligibilityCompactJWS;
599+
592600
List<Object?> _toList() {
593-
return <Object?>[appAccountToken, quantity, promotionalOffer, winBackOfferId];
601+
return <Object?>[
602+
appAccountToken,
603+
quantity,
604+
promotionalOffer,
605+
winBackOfferId,
606+
introductoryOfferEligibilityCompactJWS,
607+
];
594608
}
595609

596610
Object encode() {
@@ -604,6 +618,7 @@ class SK2ProductPurchaseOptionsMessage {
604618
quantity: result[1] as int?,
605619
promotionalOffer: result[2] as SK2SubscriptionOfferPurchaseMessage?,
606620
winBackOfferId: result[3] as String?,
621+
introductoryOfferEligibilityCompactJWS: result[4] as String?,
607622
);
608623
}
609624

@@ -619,7 +634,11 @@ class SK2ProductPurchaseOptionsMessage {
619634
return _deepEquals(appAccountToken, other.appAccountToken) &&
620635
_deepEquals(quantity, other.quantity) &&
621636
_deepEquals(promotionalOffer, other.promotionalOffer) &&
622-
_deepEquals(winBackOfferId, other.winBackOfferId);
637+
_deepEquals(winBackOfferId, other.winBackOfferId) &&
638+
_deepEquals(
639+
introductoryOfferEligibilityCompactJWS,
640+
other.introductoryOfferEligibilityCompactJWS,
641+
);
623642
}
624643

625644
@override
@@ -628,7 +647,7 @@ class SK2ProductPurchaseOptionsMessage {
628647

629648
@override
630649
String toString() {
631-
return 'SK2ProductPurchaseOptionsMessage(appAccountToken: $appAccountToken, quantity: $quantity, promotionalOffer: $promotionalOffer, winBackOfferId: $winBackOfferId)';
650+
return 'SK2ProductPurchaseOptionsMessage(appAccountToken: $appAccountToken, quantity: $quantity, promotionalOffer: $promotionalOffer, winBackOfferId: $winBackOfferId, introductoryOfferEligibilityCompactJWS: $introductoryOfferEligibilityCompactJWS)';
632651
}
633652
}
634653

‎packages/in_app_purchase/in_app_purchase_storekit/lib/src/store_kit_2_wrappers/sk2_product_wrapper.dart‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -289,6 +289,7 @@ class SK2ProductPurchaseOptions {
289289
this.quantity,
290290
this.promotionalOffer,
291291
this.winBackOfferId,
292+
this.introductoryOfferEligibilityCompactJWS,
292293
});
293294

294295
/// Sets a UUID to associate the purchase with an account in your system.
@@ -303,13 +304,20 @@ class SK2ProductPurchaseOptions {
303304
/// Sets a win back offer to a purchase.
304305
final String? winBackOfferId;
305306

307+
/// Sets the customer's introductory offer eligibility for this purchase,
308+
/// as a compact JWS signed by your server.
309+
///
310+
/// See [Sk2PurchaseParam.introductoryOfferEligibilityCompactJWS].
311+
final String? introductoryOfferEligibilityCompactJWS;
312+
306313
/// Convert to pigeon representation [SK2ProductPurchaseOptionsMessage].
307314
SK2ProductPurchaseOptionsMessage convertToPigeon() {
308315
return SK2ProductPurchaseOptionsMessage(
309316
appAccountToken: appAccountToken,
310317
quantity: quantity,
311318
winBackOfferId: winBackOfferId,
312319
promotionalOffer: promotionalOffer,
320+
introductoryOfferEligibilityCompactJWS: introductoryOfferEligibilityCompactJWS,
313321
);
314322
}
315323
}

‎packages/in_app_purchase/in_app_purchase_storekit/lib/src/types/sk2_purchase_param.dart‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ class Sk2PurchaseParam extends PurchaseParam {
1616
this.quantity = 1,
1717
this.winBackOfferId,
1818
this.promotionalOffer,
19+
this.introductoryOfferEligibilityCompactJWS,
1920
});
2021

2122
/// Creates a [Sk2PurchaseParam] from a [ProductDetails] and a [SK2SubscriptionOffer].
@@ -54,4 +55,32 @@ class Sk2PurchaseParam extends PurchaseParam {
5455

5556
/// The promotional offer identifier to apply to the purchase.
5657
final SK2PromotionalOffer? promotionalOffer;
58+
59+
/// A compact JWS, signed by your server, that sets the customer's
60+
/// eligibility for an introductory offer on this purchase.
61+
///
62+
/// When non-null this is forwarded verbatim to StoreKit as
63+
/// [`Product.PurchaseOption.introductoryOfferEligibility(compactJWS:)`](https://developer.apple.com/documentation/storekit/product/purchaseoption/introductoryoffereligibility(compactjws:)).
64+
/// When null, no such purchase option is set and the App Store applies its
65+
/// own default introductory offer eligibility.
66+
///
67+
/// The JWS is signed on your server with an App Store Connect In-App
68+
/// Purchase key; see
69+
/// [Generating JWS to sign App Store requests](https://developer.apple.com/documentation/storekit/generating-jws-to-sign-app-store-requests).
70+
/// Its `allowIntroductoryOffer` claim determines whether the customer is
71+
/// eligible, and can both grant an introductory offer to a customer the App
72+
/// Store would consider ineligible and block one for a customer it would
73+
/// consider eligible.
74+
///
75+
/// This value is passed through untouched: the plugin never generates,
76+
/// parses, validates or inspects it.
77+
///
78+
/// This is **not** the same as [InAppPurchaseStoreKitPlatformAddition.isIntroductoryOfferEligible],
79+
/// which reports the App Store's *default* eligibility for a product. This
80+
/// property is a pricing decision supplied by a trusted server, and is
81+
/// neither entitlement nor purchase verification.
82+
///
83+
/// Available on iOS 15.0+ and macOS 12.0+; the underlying StoreKit API is
84+
/// back deployed, so no additional OS version check is required.
85+
final String? introductoryOfferEligibilityCompactJWS;
5786
}

‎packages/in_app_purchase/in_app_purchase_storekit/pigeons/sk2_pigeon.dart‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,12 +154,20 @@ class SK2ProductPurchaseOptionsMessage {
154154
this.quantity = 1,
155155
this.promotionalOffer,
156156
this.winBackOfferId,
157+
this.introductoryOfferEligibilityCompactJWS,
157158
});
158159

159160
final String? appAccountToken;
160161
final int? quantity;
161162
final SK2SubscriptionOfferPurchaseMessage? promotionalOffer;
162163
final String? winBackOfferId;
164+
165+
/// A compact JWS, signed by the developer's server, that sets the customer's
166+
/// eligibility for an introductory offer on this purchase.
167+
///
168+
/// This is passed to StoreKit verbatim; it is never parsed or validated
169+
/// client-side.
170+
final String? introductoryOfferEligibilityCompactJWS;
163171
}
164172

165173
class SK2TransactionMessage {

‎packages/in_app_purchase/in_app_purchase_storekit/pubspec.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ name: in_app_purchase_storekit
22
description: An implementation for the iOS and macOS platforms of the Flutter `in_app_purchase` plugin. This uses the StoreKit Framework.
33
repository: https://github.com/flutter/packages/tree/main/packages/in_app_purchase/in_app_purchase_storekit
44
issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+in_app_purchase%22
5-
version: 0.4.11+2
5+
version: 0.4.12
66

77
environment:
88
sdk: ^3.10.0

0 commit comments

Comments
 (0)