@invonetwork/web-sdk 3.34.1 → 3.35.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -0
- package/README.md +95 -2
- package/dist/{chunk-3BR7URPM.js → chunk-BGCSSWVL.js} +104 -2
- package/dist/{chunk-PEYWNML4.js → chunk-SCFK6IVH.js} +3 -3
- package/dist/{chunk-MJXQ3Q7C.js → chunk-XN6MCLQV.js} +229 -68
- package/dist/game-server.cjs +291 -71
- package/dist/game-server.d.cts +3 -3
- package/dist/game-server.d.ts +3 -3
- package/dist/game-server.js +4 -4
- package/dist/game.cjs +102 -0
- package/dist/game.d.cts +2 -2
- package/dist/game.d.ts +2 -2
- package/dist/game.js +2 -2
- package/dist/{hosted-approval-CZ5EYFlM.d.ts → hosted-approval-DIYUGgHi.d.ts} +1 -1
- package/dist/{hosted-approval-B6yY7ExK.d.cts → hosted-approval-VQ3uyeDh.d.cts} +1 -1
- package/dist/index.cjs +102 -0
- package/dist/index.d.cts +4 -4
- package/dist/index.d.ts +4 -4
- package/dist/index.js +2 -2
- package/dist/{server-JARGQrat.d.ts → server-CMJHOmYL.d.ts} +117 -6
- package/dist/{server-A1s7zqzG.d.cts → server-DF-BZU0B.d.cts} +117 -6
- package/dist/server.cjs +330 -64
- package/dist/server.d.cts +2 -2
- package/dist/server.d.ts +2 -2
- package/dist/server.js +2 -2
- package/dist/{types-B4J9Ifd2.d.ts → types-Dv0UavA9.d.cts} +146 -1
- package/dist/{types-B4J9Ifd2.d.cts → types-Dv0UavA9.d.ts} +146 -1
- package/docs/apple-in-app-purchases.md +382 -0
- package/package.json +2 -1
|
@@ -0,0 +1,382 @@
|
|
|
1
|
+
# Apple In-App Purchases (StoreKit 2)
|
|
2
|
+
|
|
3
|
+
This guide takes an iOS game from nothing to selling coins through Apple In-App Purchase with
|
|
4
|
+
INVO, using `@invonetwork/web-sdk/server`. The player pays Apple through StoreKit 2. Your game
|
|
5
|
+
server sends Apple's signed transaction to INVO. INVO verifies it against Apple's root
|
|
6
|
+
certificate, checks it belongs to your app, credits the coins once, and sends you the usual
|
|
7
|
+
`purchase.completed` webhook. Apple is the merchant of record and collects any consumption tax;
|
|
8
|
+
Apple pays you, and INVO collects the coins' value from your INVO billing account.
|
|
9
|
+
|
|
10
|
+
Everything here runs on your **server**. The game's iOS key is a secret and never ships inside
|
|
11
|
+
the app.
|
|
12
|
+
|
|
13
|
+
- [How it works in one paragraph](#how-it-works-in-one-paragraph)
|
|
14
|
+
- [Prerequisites](#prerequisites)
|
|
15
|
+
- [The purchase flow](#the-purchase-flow)
|
|
16
|
+
- [When to call Transaction.finish()](#when-to-call-transactionfinish)
|
|
17
|
+
- [Errors](#errors)
|
|
18
|
+
- [Held purchases (APPLE_CREDIT_PENDING)](#held-purchases-apple_credit_pending)
|
|
19
|
+
- [Refunds and webhooks](#refunds-and-webhooks)
|
|
20
|
+
- [App Review on production](#app-review-on-production)
|
|
21
|
+
- [Verifying your app with INVO](#verifying-your-app-with-invo)
|
|
22
|
+
- [Sandbox testing](#sandbox-testing)
|
|
23
|
+
- [Complete server example](#complete-server-example)
|
|
24
|
+
- [Checklist before you submit to App Review](#checklist-before-you-submit-to-app-review)
|
|
25
|
+
|
|
26
|
+
## How it works in one paragraph
|
|
27
|
+
|
|
28
|
+
Apple takes the player's money **before** INVO sees the purchase. So INVO's only chance to say
|
|
29
|
+
"not now" is before the player taps Buy: your game asks `appleProducts()` before every purchase
|
|
30
|
+
and offers only products marked `available`. After payment, INVO never refuses a genuine
|
|
31
|
+
purchase of your product for a reason the player cannot fix. It credits the coins, or, in the
|
|
32
|
+
few cases it cannot credit yet, it **holds** the purchase and credits it on a later retry. Your
|
|
33
|
+
game finishes the StoreKit transaction only when INVO's answer says `finish: true`; until then
|
|
34
|
+
StoreKit keeps redelivering it, and every redelivery is a safe retry.
|
|
35
|
+
|
|
36
|
+
## Prerequisites
|
|
37
|
+
|
|
38
|
+
1. **Consumable products in App Store Connect.** Create one consumable In-App Purchase per coin
|
|
39
|
+
pack, for example `com.example.game.coins.100`. Only consumables can buy coins (other types
|
|
40
|
+
are refused with `APPLE_PRODUCT_TYPE_UNSUPPORTED`). Give each a fixed coin amount in its
|
|
41
|
+
display name; INVO credits a fixed number of coins per product.
|
|
42
|
+
2. **The Apple configuration in the INVO console** (Apple In-App Purchases, on the game). The
|
|
43
|
+
account owner saves:
|
|
44
|
+
- the **bundle id** (`com.example.game`) and, optionally, the numeric **Apple ID** of the app;
|
|
45
|
+
- whether the app is in Apple's **Small Business Program** (15% commission, else 30%; INVO
|
|
46
|
+
uses it to estimate your proceeds);
|
|
47
|
+
- the **products**: each App Store product id, the coins it credits, a label, and its US App
|
|
48
|
+
Store price (`price_usd`, optional but recommended: it is the USD figure on non-USD
|
|
49
|
+
storefronts, and the console warns when the estimated proceeds fall below the coin value
|
|
50
|
+
INVO bills, `PROCEEDS_BELOW_COIN_VALUE`). The list is the full list: a product you remove
|
|
51
|
+
stops being offered, and is never deleted, so past purchases still resolve;
|
|
52
|
+
- up to 10 **App Review accounts** (see [App Review on production](#app-review-on-production)).
|
|
53
|
+
3. **The game's iOS key on the Apple rail.** Create an iOS SDK key for the game. Saving the Apple
|
|
54
|
+
configuration with `enabled: true` points that key at the Apple rail; the console shows
|
|
55
|
+
`ios_key.rail`. A card purchase made with that key is refused with `WRONG_RAIL_ENDPOINT`
|
|
56
|
+
(`err.isAppleEndpointRequired`), and the Apple routes refuse any other key with
|
|
57
|
+
`RAIL_CHANNEL_MISMATCH`.
|
|
58
|
+
4. **Billing set up on your INVO developer account.** Apple pays you, so INVO collects the
|
|
59
|
+
coins' value from the payment method on your INVO billing account, as on other storefronts
|
|
60
|
+
that pay the developer directly. Without billing, products show
|
|
61
|
+
`unavailableReason: "PARTNER_BILLING_NOT_SET_UP"`.
|
|
62
|
+
5. **App Store Server Notifications V2 pointed at INVO.** The console shows your
|
|
63
|
+
`notification_url`. In App Store Connect (App Information, App Store Server Notifications),
|
|
64
|
+
set the **Production** server URL to the URL shown in the live console, and the **Sandbox**
|
|
65
|
+
server URL to the URL shown in the test console for your sandbox game. INVO uses these for
|
|
66
|
+
refunds and to verify that you own the app.
|
|
67
|
+
|
|
68
|
+
No App Store Server API key is needed: a StoreKit 2 transaction verifies against Apple's
|
|
69
|
+
public root certificate.
|
|
70
|
+
|
|
71
|
+
## The purchase flow
|
|
72
|
+
|
|
73
|
+
1. **Before every purchase, ask INVO what may be sold.**
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
const { canSell, unavailableReason, products } = await server.appleProducts();
|
|
77
|
+
const offer = canSell ? products.filter((p) => p.available) : [];
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Ask StoreKit (`Product.products(for:)`) for exactly the `productId`s INVO returns, and
|
|
81
|
+
hide or disable any with `available: false`. `unavailableReason` (for the whole game, and
|
|
82
|
+
per product) is one of:
|
|
83
|
+
|
|
84
|
+
| Reason | Meaning |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `APPLE_NOT_VERIFIED` | production has not yet confirmed you own the app ([Verifying your app](#verifying-your-app-with-invo)) |
|
|
87
|
+
| `PARTNER_BILLING_NOT_SET_UP` | your INVO developer account has no billing set up |
|
|
88
|
+
| `PARTNER_RAIL_SUSPENDED` | your account's settlement is suspended (for example after failed collection) |
|
|
89
|
+
| `PARTNER_CREDIT_UNAVAILABLE` | not enough prepaid balance or credit for this product's coins right now |
|
|
90
|
+
|
|
91
|
+
Treat any other value as "not available". Do not cache the answer across purchases.
|
|
92
|
+
|
|
93
|
+
2. **The player buys with StoreKit 2.** Set `appAccountToken` to a UUID that identifies the
|
|
94
|
+
player in your game, so INVO can refuse a transaction made for someone else. Call
|
|
95
|
+
`product.purchase(options: [.appAccountToken(uuid)])`. When StoreKit returns
|
|
96
|
+
`.success(.verified(transaction))`, send `verificationResult.jwsRepresentation` and the
|
|
97
|
+
player's email to **your server**. Do not finish the transaction yet. Also listen to
|
|
98
|
+
`Transaction.updates` at launch and forward every unfinished transaction the same way:
|
|
99
|
+
that is how held and interrupted purchases come back.
|
|
100
|
+
|
|
101
|
+
3. **Your server verifies with INVO.**
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
const result = await server.verifyApplePurchase({
|
|
105
|
+
playerEmail,
|
|
106
|
+
signedTransaction, // jwsRepresentation, unchanged
|
|
107
|
+
appAccountToken, // optional: the UUID the app set
|
|
108
|
+
metadata: { playerId }, // optional: echoed on purchase.completed and purchase.refunded
|
|
109
|
+
});
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
INVO checks, in order: Apple's signature chain and ES256 signature (nothing is trusted
|
|
113
|
+
before this); the bundle id (and Apple ID when registered); the environment for this INVO
|
|
114
|
+
deployment; that the product is a consumable; that Apple has not revoked it; that the
|
|
115
|
+
product is registered for your game (a product you retired still credits, so a purchase made
|
|
116
|
+
before you retired it is never stranded); the `appAccountToken`, when you send one; that the
|
|
117
|
+
purchase is not older than your Apple configuration; that the coins are in proportion to the
|
|
118
|
+
price Apple signed (at most 2x) and under the per-purchase maximum; and that this Apple
|
|
119
|
+
transaction has never been used before, in any INVO game.
|
|
120
|
+
|
|
121
|
+
A `200` returns:
|
|
122
|
+
|
|
123
|
+
```json
|
|
124
|
+
{"status": "credited", "order_id": "ORD_...", "transaction_id": "2000000123456789",
|
|
125
|
+
"product_id": "com.example.game.coins.100", "coins": 100, "balance": "1250.00",
|
|
126
|
+
"environment": "Production", "test_mode": false, "finish": true}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
which the SDK maps to `{ status, orderId, transactionId, productId, coins, balance,
|
|
130
|
+
environment, testMode, finish }`. `status` is `"credited"` (added by this call) or
|
|
131
|
+
`"already_credited"` (a replay: the coins were added earlier; `balance` is `null` unless
|
|
132
|
+
you name the same player).
|
|
133
|
+
|
|
134
|
+
4. **Your server tells the app whether to finish.** Pass the result, or the thrown error, to
|
|
135
|
+
`shouldFinishAppleTransaction()` and return the answer to the app, which calls
|
|
136
|
+
`transaction.finish()` only when it is `true`.
|
|
137
|
+
|
|
138
|
+
## When to call Transaction.finish()
|
|
139
|
+
|
|
140
|
+
Every verify-purchase answer, success or error, carries a boolean `finish`. It is on the result
|
|
141
|
+
(`result.finish`) and on the error (`err.finish`), and `shouldFinishAppleTransaction(outcome)`
|
|
142
|
+
reads it for you. It is `true` for exactly these outcomes:
|
|
143
|
+
|
|
144
|
+
| Outcome | Why finish |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `status: "credited"` | the coins were added |
|
|
147
|
+
| `status: "already_credited"` | the coins were added by an earlier call |
|
|
148
|
+
| `APPLE_TRANSACTION_REVOKED` | Apple refunded or revoked it; nothing can ever be delivered |
|
|
149
|
+
| `APPLE_TRANSACTION_ALREADY_USED` | credited in another INVO game; it can never credit here |
|
|
150
|
+
| `APPLE_TRANSACTION_TOO_OLD` | bought before the game sold through INVO; it can never credit |
|
|
151
|
+
|
|
152
|
+
On **anything else**, leave the transaction unfinished. That includes `APPLE_CREDIT_PENDING`,
|
|
153
|
+
every other refusal, a network error and a timeout (the credit may or may not have landed; a
|
|
154
|
+
retry finds out without crediting twice). StoreKit redelivers an unfinished transaction, and
|
|
155
|
+
your server sends it to `verifyApplePurchase` again.
|
|
156
|
+
|
|
157
|
+
If an answer carries no `finish` (a refusal from outside the Apple route, such as an invalid
|
|
158
|
+
key, or an older INVO release), `shouldFinishAppleTransaction` falls back to the same rule:
|
|
159
|
+
the two success statuses and the three codes above, exported as `APPLE_FINISH_ERROR_CODES`.
|
|
160
|
+
|
|
161
|
+
Finishing too early is the one mistake that cannot be undone: a finished transaction is never
|
|
162
|
+
redelivered, so a purchase that was held would never be credited.
|
|
163
|
+
|
|
164
|
+
## Errors
|
|
165
|
+
|
|
166
|
+
The error body is `{"status": "error", "error_code": "...", "message": "...", "finish": false}`.
|
|
167
|
+
The SDK throws it as an `InvoError`; branch on the predicates, not the message.
|
|
168
|
+
|
|
169
|
+
| Code | HTTP | Predicate | Finish? | What to do |
|
|
170
|
+
|---|---|---|---|---|
|
|
171
|
+
| `APPLE_SIGNATURE_INVALID` | 400 | `err.isAppleSignatureInvalid` | no | not a genuine Apple transaction; send `jwsRepresentation` unchanged |
|
|
172
|
+
| `APPLE_BUNDLE_MISMATCH` | 400 | `err.isAppleBundleMismatch` | no | another app's transaction, or the wrong bundle id or Apple ID in the console |
|
|
173
|
+
| `APPLE_ENVIRONMENT_NOT_ALLOWED` | 400 | `err.isAppleEnvironmentNotAllowed` | no | a Production transaction sent to the INVO sandbox, or an Xcode StoreKit-testing transaction (never accepted: Apple does not sign them) |
|
|
174
|
+
| `APPLE_PRODUCT_TYPE_UNSUPPORTED` | 400 | `err.isAppleProductTypeUnsupported` | no | only consumables buy coins |
|
|
175
|
+
| `APPLE_PRODUCT_UNKNOWN` | 400 | `err.isAppleProductUnknown` | no | register the product id in the INVO console, then retry |
|
|
176
|
+
| `INVALID_METADATA` | 400 | `err.isInvalidMetadata` | no | fix `metadata`, then retry |
|
|
177
|
+
| `INVALID_INPUT` | 400 | `err.isInvalidInput` | no | fix the request (a missing email, a bad `appAccountToken`); `status === 0` means the SDK refused it before sending |
|
|
178
|
+
| `APPLE_REVIEW_ACCOUNT_REQUIRED` | 403 | `err.isAppleReviewAccountRequired` | no | a Sandbox purchase on production by an account not on your App Review list |
|
|
179
|
+
| `APPLE_TRANSACTION_REVOKED` | 409 | `err.isAppleTransactionRevoked` | **yes** | Apple refunded or revoked it; grant nothing |
|
|
180
|
+
| `APPLE_TRANSACTION_ALREADY_USED` | 409 | `err.isAppleTransactionAlreadyUsed` | **yes** | credited in another INVO game; grant nothing here |
|
|
181
|
+
| `APPLE_TRANSACTION_TOO_OLD` | 409 | `err.isAppleTransactionTooOld` | **yes** | bought before the game sold through INVO; grant nothing |
|
|
182
|
+
| `APPLE_VALUE_EXCEEDS_PRICE` | 409 | `err.isAppleValueExceedsPrice` | no | the product's coins are out of proportion to its price; fix the mapping in the console, then retry |
|
|
183
|
+
| `APPLE_ACCOUNT_TOKEN_MISMATCH` | 409 | `err.isAppleAccountTokenMismatch` | no | the transaction was made for a different player; send the right player |
|
|
184
|
+
| `APPLE_NOT_CONFIGURED` | 409 | `err.isAppleNotConfigured` | no | no Apple configuration, or it is turned off; retry once fixed |
|
|
185
|
+
| `APPLE_NOT_VERIFIED` | 409 | `err.isAppleNotVerified` | no | production has not verified the app yet; retry once verified |
|
|
186
|
+
| `RAIL_CHANNEL_MISMATCH` | 409 | `err.isRailChannelMismatch` | no | the key is not the game's iOS key on the Apple rail |
|
|
187
|
+
| `APPLE_REVIEW_PURCHASE_LIMIT` | 429 | `err.isAppleReviewPurchaseLimit` | no | today's App Review cap on production (per UTC day); retry the next day |
|
|
188
|
+
| `APPLE_CREDIT_PENDING` | 503 | `err.isAppleCreditPending` | no | verified and held; retry later ([Held purchases](#held-purchases-apple_credit_pending)) |
|
|
189
|
+
| anything else, a network error, a timeout | | | no | retry |
|
|
190
|
+
|
|
191
|
+
`verifyApplePurchase` is safe to retry, and the SDK retries transient failures (429 and 5xx)
|
|
192
|
+
on its own, because INVO credits each Apple transaction at most once.
|
|
193
|
+
|
|
194
|
+
## Held purchases (APPLE_CREDIT_PENDING)
|
|
195
|
+
|
|
196
|
+
Within a bounded allowance, a purchase your INVO billing cannot cover at that moment is still
|
|
197
|
+
credited, and your account owes its value: Apple paid you for exactly these coins. INVO
|
|
198
|
+
**holds** the purchase instead (`503 APPLE_CREDIT_PENDING`, `finish: false`) when:
|
|
199
|
+
|
|
200
|
+
- the purchase is beyond that allowance (per purchase, and per developer per 24 hours);
|
|
201
|
+
- your developer account is suspended, or has no billing account;
|
|
202
|
+
- INVO has paused payments on the account or for maintenance.
|
|
203
|
+
|
|
204
|
+
A held purchase is verified and recorded. It credits on a later retry once the cause is fixed,
|
|
205
|
+
for example when you fund your account. Keep the transaction unfinished; StoreKit redelivers it,
|
|
206
|
+
or your server can retry on a schedule. Never ask the player to pay again. Holds are alerted to
|
|
207
|
+
INVO. Keeping your billing funded and watching `appleProducts()` (which stops offering products
|
|
208
|
+
before this happens) keeps holds rare.
|
|
209
|
+
|
|
210
|
+
## Refunds and webhooks
|
|
211
|
+
|
|
212
|
+
`purchase.completed` fires for every Apple credit, like every other rail. It carries
|
|
213
|
+
`rail: "apple"`, `channel: "ios"`, your `metadata`, and an `apple` block:
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
"apple": {"transaction_id": "2000000123456789", "original_transaction_id": "2000000123456789",
|
|
217
|
+
"product_id": "com.example.game.coins.100", "environment": "Production",
|
|
218
|
+
"storefront": "USA", "price": "3.99", "currency": "USD",
|
|
219
|
+
"charged_usd_estimated": false, "test_mode": false}
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`usd_amount` is what the player paid in USD: exact on a USD storefront, and on other
|
|
223
|
+
storefronts the product's registered US price, with `charged_usd_estimated: true`. `price` is
|
|
224
|
+
per unit in the storefront's currency. In TypeScript the block is `AppleWebhookDetails`, at
|
|
225
|
+
`data.apple` on `PurchaseCompletedData` and `PurchaseEventData`.
|
|
226
|
+
|
|
227
|
+
When Apple refunds or revokes a purchase, App Store Server Notifications tell INVO, and INVO:
|
|
228
|
+
|
|
229
|
+
- takes back the coins the player still holds from that purchase, never below zero;
|
|
230
|
+
- credits your INVO billing account back only for the coins it took back (coins the player
|
|
231
|
+
already spent were used, so you stay billed for them);
|
|
232
|
+
- sends `purchase.refunded` with `rail: "apple"`, your `metadata`, the `apple` block,
|
|
233
|
+
`currency_debited` and `new_balance`.
|
|
234
|
+
|
|
235
|
+
A refund that arrives before your server first reports the purchase blocks that purchase's
|
|
236
|
+
credit: the later verify answers `APPLE_TRANSACTION_REVOKED` (finish it). A refund Apple later
|
|
237
|
+
reverses is reviewed by INVO and adjusted by hand; it is never re-credited automatically.
|
|
238
|
+
|
|
239
|
+
Verify every webhook with `verifyWebhook` (see the README's Webhooks section), and grant coins
|
|
240
|
+
from `purchase.completed` or from the `credited` result, never from both without deduplicating
|
|
241
|
+
on `order_id`.
|
|
242
|
+
|
|
243
|
+
## App Review on production
|
|
244
|
+
|
|
245
|
+
Apple's reviewers buy with Sandbox accounts, against your production build and your production
|
|
246
|
+
server. INVO production therefore accepts **Sandbox** transactions, as `testMode: true`, only:
|
|
247
|
+
|
|
248
|
+
- for the player emails on the game's App Review list in the console (up to 10); any other
|
|
249
|
+
account is refused with `APPLE_REVIEW_ACCOUNT_REQUIRED`;
|
|
250
|
+
- at quantity 1;
|
|
251
|
+
- up to 20 purchases and $100 of coin value per game per UTC day
|
|
252
|
+
(`APPLE_REVIEW_PURCHASE_LIMIT` beyond that).
|
|
253
|
+
|
|
254
|
+
Give App Review the same email you put on the list, in the review notes. These purchases go
|
|
255
|
+
through the normal accrual, so they are billed like real ones. Their refund notifications go to
|
|
256
|
+
the Sandbox notification URL, so production does not take those coins back.
|
|
257
|
+
|
|
258
|
+
## Verifying your app with INVO
|
|
259
|
+
|
|
260
|
+
Production sells only once INVO has confirmed you own the App Store app (`APPLE_NOT_VERIFIED`
|
|
261
|
+
until then). The first genuine, recent App Store Server Notification INVO receives at your
|
|
262
|
+
production `notification_url` verifies it, because only the app's owner in App Store Connect can
|
|
263
|
+
point Apple's notifications there. To trigger one, call the App Store Server API's "Request a
|
|
264
|
+
Test Notification" endpoint for production with your own App Store Server API key, or wait for
|
|
265
|
+
the first real notification. The console
|
|
266
|
+
shows `verified` and `verified_at`. INVO can also verify an app by hand on request.
|
|
267
|
+
|
|
268
|
+
Changing the bundle id before the game has sold through Apple clears verification; after the
|
|
269
|
+
first sale the bundle id cannot change (`APPLE_BUNDLE_LOCKED`). Each bundle id has one verified
|
|
270
|
+
owner across INVO (`APPLE_BUNDLE_ALREADY_REGISTERED`).
|
|
271
|
+
|
|
272
|
+
## Sandbox testing
|
|
273
|
+
|
|
274
|
+
- The INVO **sandbox** accepts **Sandbox** transactions only and does not require verification.
|
|
275
|
+
Use an App Store Sandbox tester on a device, with your sandbox game's iOS key and
|
|
276
|
+
`baseUrl: "https://sandbox.invo.network/sandbox"`.
|
|
277
|
+
- Xcode's local StoreKit configuration file produces transactions Apple does not sign. INVO
|
|
278
|
+
refuses them (`APPLE_ENVIRONMENT_NOT_ALLOWED`). Test against App Store Sandbox instead.
|
|
279
|
+
- On the INVO sandbox, `testMode` is `false`: every transaction there is a Sandbox one.
|
|
280
|
+
|
|
281
|
+
## Complete server example
|
|
282
|
+
|
|
283
|
+
An Express server with two routes the app calls: one before showing the store, one after each
|
|
284
|
+
StoreKit purchase (and for every transaction from `Transaction.updates`).
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
import express from "express";
|
|
288
|
+
import {
|
|
289
|
+
InvoServer,
|
|
290
|
+
shouldFinishAppleTransaction,
|
|
291
|
+
type InvoError,
|
|
292
|
+
} from "@invonetwork/web-sdk/server";
|
|
293
|
+
|
|
294
|
+
const invo = new InvoServer({
|
|
295
|
+
gameSecret: process.env.INVO_IOS_KEY!, // the game's iOS key, server-side only
|
|
296
|
+
baseUrl: process.env.INVO_BASE_URL!, // "https://invo.network" or the sandbox URL
|
|
297
|
+
});
|
|
298
|
+
|
|
299
|
+
const app = express();
|
|
300
|
+
app.use(express.json());
|
|
301
|
+
|
|
302
|
+
// 1. Before every purchase: which products may be offered right now.
|
|
303
|
+
app.get("/store/apple-products", async (_req, res) => {
|
|
304
|
+
try {
|
|
305
|
+
const { canSell, unavailableReason, products } = await invo.appleProducts();
|
|
306
|
+
res.json({
|
|
307
|
+
canSell,
|
|
308
|
+
unavailableReason,
|
|
309
|
+
products: products
|
|
310
|
+
.filter((p) => canSell && p.available)
|
|
311
|
+
.map((p) => ({ productId: p.productId, coins: p.coins, label: p.label })),
|
|
312
|
+
});
|
|
313
|
+
} catch {
|
|
314
|
+
// INVO cannot be asked: sell nothing rather than take money that might not credit.
|
|
315
|
+
res.json({ canSell: false, unavailableReason: "UNAVAILABLE", products: [] });
|
|
316
|
+
}
|
|
317
|
+
});
|
|
318
|
+
|
|
319
|
+
// 2. After StoreKit returns a verified transaction (and for each one in Transaction.updates).
|
|
320
|
+
app.post("/store/apple-verify", async (req, res) => {
|
|
321
|
+
const playerEmail = currentPlayerEmail(req); // from YOUR session, never from the app body
|
|
322
|
+
const { signedTransaction, appAccountToken } = req.body ?? {};
|
|
323
|
+
|
|
324
|
+
let outcome: unknown;
|
|
325
|
+
try {
|
|
326
|
+
const result = await invo.verifyApplePurchase({
|
|
327
|
+
playerEmail,
|
|
328
|
+
signedTransaction,
|
|
329
|
+
appAccountToken,
|
|
330
|
+
metadata: { playerId: currentPlayerId(req) },
|
|
331
|
+
});
|
|
332
|
+
outcome = result;
|
|
333
|
+
if (result.status === "credited") {
|
|
334
|
+
// Coins are in the player's INVO balance. Grant any in-game effect here or on the
|
|
335
|
+
// purchase.completed webhook, deduplicated on result.orderId.
|
|
336
|
+
}
|
|
337
|
+
} catch (err) {
|
|
338
|
+
outcome = err;
|
|
339
|
+
const e = err as InvoError;
|
|
340
|
+
if (e.isAppleCreditPending) {
|
|
341
|
+
// Verified and held: the coins will credit on a later retry. Tell the player the
|
|
342
|
+
// purchase is being processed; never ask them to pay again.
|
|
343
|
+
} else if (e.isAppleProductUnknown || e.isAppleValueExceedsPrice) {
|
|
344
|
+
// A console setup problem on your side: alert your team.
|
|
345
|
+
}
|
|
346
|
+
}
|
|
347
|
+
|
|
348
|
+
// The app calls transaction.finish() only when this is true.
|
|
349
|
+
res.json({ finish: shouldFinishAppleTransaction(outcome) });
|
|
350
|
+
});
|
|
351
|
+
|
|
352
|
+
app.listen(3000);
|
|
353
|
+
|
|
354
|
+
// Your own session lookups.
|
|
355
|
+
declare function currentPlayerEmail(req: express.Request): string;
|
|
356
|
+
declare function currentPlayerId(req: express.Request): string;
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
On the device, the matching Swift is short:
|
|
360
|
+
|
|
361
|
+
```swift
|
|
362
|
+
let result = try await product.purchase(options: [.appAccountToken(playerUUID)])
|
|
363
|
+
if case .success(let verification) = result, case .verified(let transaction) = verification {
|
|
364
|
+
let finish = try await myServer.verifyApple(jws: verification.jwsRepresentation,
|
|
365
|
+
appAccountToken: playerUUID)
|
|
366
|
+
if finish { await transaction.finish() }
|
|
367
|
+
}
|
|
368
|
+
```
|
|
369
|
+
|
|
370
|
+
Run the same `verifyApple` then `finish` step for every transaction in `Transaction.updates` at
|
|
371
|
+
launch.
|
|
372
|
+
|
|
373
|
+
## Checklist before you submit to App Review
|
|
374
|
+
|
|
375
|
+
- Consumable products exist in App Store Connect and in the INVO console with the same ids.
|
|
376
|
+
- The game's iOS key shows the Apple rail in the console.
|
|
377
|
+
- Billing is set up, and `appleProducts()` on production shows `canSell: true`.
|
|
378
|
+
- Both notification URLs are set in App Store Connect, and production shows `verified`.
|
|
379
|
+
- The App Review email is on the game's App Review list and in your review notes.
|
|
380
|
+
- The app asks `appleProducts()` before showing the store, offers only `available` products,
|
|
381
|
+
verifies from your server, and finishes only when `finish` is `true`.
|
|
382
|
+
- The app forwards `Transaction.updates` to your server at launch.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@invonetwork/web-sdk",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.35.0",
|
|
4
4
|
"description": "INVO Web SDK — currency purchase, passkey (WebAuthn) verification, loyalty, and a drop-in game economy layer (wallet, shop, hosted checkout) for partner web platforms and browser games.",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE",
|
|
6
6
|
"private": false,
|
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
"dist",
|
|
22
22
|
"!dist/**/*.map",
|
|
23
23
|
"README.md",
|
|
24
|
+
"docs/apple-in-app-purchases.md",
|
|
24
25
|
"LICENSE",
|
|
25
26
|
"CHANGELOG.md"
|
|
26
27
|
],
|