npm install --save @withkoji/iap|
Warning
|
This package is deprecated and is included only for backwards compatibility. For new templates, use withkoji-koji-core.html. |
The @withkoji/iap package enables you to implement in-app purchases from your Koji templates. For example, require a purchase to unlock a premium asset or a game. This package provides frontend methods, for managing transactions with users, and backend methods, for validating purchases against receipts.
To implement a basic purchase flow in your template, use getToken on the frontend to obtain the current user’s token. Then, use the callback function to route a request to the backend.
On the backend, use resolveReceipts to determine whether the user has purchased the product and return appropriate information to the frontend.
Finally, on the frontend, display the appropriate experience based on whether or not the product has been purchased.
For example, display a premium image that has been purchased.
Or, if the user hasn’t purchased the image, display a Purchase button and use startPurchase to initiate a transaction when the user clicks the button.
Install the package in the frontend and backend services of your Koji project.
npm install --save @withkoji/iap|
Important
|
To support instant remixes of your template, you must also install the withkoji-vcc-package.html package and implement the VccMiddleware on your backend server.
This middleware maintains the environment variables for instant remixes, ensuring that purchases are applied to the correct remix version.
|
To enable in-app purchases for your Koji template, you must implement the Iap class and define the InAppPurchases entitlements.
Instantiates Iap.
projectID – (Backend only) String, unique identifier for the Koji.
projectToken – (Backend only) String, secret key for the Koji.
|
Tip
|
When instantiating Iap on the backend, you must provide these parameters, which are available as environment variables at runtime.
For instant remixes, you must implement VccMiddleware to manage these variables.
See withkoji-vcc-package.html.
|
import Iap from '@withkoji/iap';
// Frontend
const iap = new Iap();
// Backend
const iap = new Iap(
res.locals.KOJI_PROJECT_ID,
res.locals.KOJI_PROJECT_TOKEN,
);Gets a token identifying the current user, and invokes a callback function to handle backend requests for the user’s purchases.
handler – Function, handles backend requests for the user’s purchases.
Receives the following property as input:
userToken – String, temporary token for the current user’s session.
|
Note
|
A user token is created when a logged-in user loads a Koji app, and destroyed when the user closes the app. If the user revisits the Koji app, a different token is generated. Tokens are specific to a user and a Koji app, so the same user will have different tokens for different apps. To resolve purchases for a given user, both the user token, obtained on the frontend, and the project token, obtained from environment variables on the backend, are necessary. |
forceRefresh – (Optional) Boolean, indicates whether to generate a new user token before invoking the callback function (false by default).
iap.getToken((token) => {
// Request user's purchases and update template based on what has or has not been purchased
});Gets the properties for a specified product to enable the template to leverage dynamic product information.
For example, you can check the stock for a product with limited quantity (via the numAvailable property), and indicate the number of remaining items.
sku – String, identifier for the product.
(Async) IapProduct object, properties of the specified product.
const product = await iap.loadProduct(sku);Retrieves the user’s receipts, which can be used to validate purchases for specific products.
userToken – String, temporary token for the current user’s session.
See getToken.
(Async) Array of IapReceipt objects, the user’s purchases.
const receipts = await iap.resolveReceipts(token);
// Look for the SKU to determine whether the user has purchased the product
hasPurchased = !!(receipts.find(({ product }) => product.sku === 'productID'));Retrieves a specific transaction receipt, which can be used to facilitate fulfillment. For example, use a dynamic receipt to upload a video response from the seller and then share that response with the buyer.
receiptId – String, unique identifier for the receipt.
(Async) IapReceipt object for the specified receipt.
const receipt = await iap.resolveReceiptById(token);
// Use custom attributes for a video response
this.setState({
instructions: receipt.attributes.message,
video: receipt.attributes.video,
});Retrieves all receipts for a specified product, which can be used to aggregate sales data.
sku – String, identifier for the product.
Products are defined in the entitlements and registered or updated when the project is deployed.
(Async) Array of IapReceipt objects for the specified product.
const receipts = await iap.resolveReceiptsBySku(sku);Prompts the user to purchase a product, and invokes a callback function to handle the results of the purchase.
sku – String, identifier for the product to purchase.
Products are defined in the entitlements and registered or updated when the project is deployed.
handler – Function, handles the results of the purchase.
Receives the following properties as input:
success – Boolean, indicates whether the purchase was successful.
userToken – String, temporary token for the current user’s session.
See getToken.
receiptId – String, unique identifier for the receipt, if the purchase was successful, or undefined, if not.
purchaseOptions– Object, custom information to add to the transaction receipt.
Contains the following properties:
amount – Number, (Optional) amount of the purchase.
customMessage – String, (Optional) custom message associated with the purchase.
This value is stored as a custom attribute on the transaction receipt.
iap.startPurchase(sku, (success, token, purchaseOptions) => {
// Update template based on whether the purchase was successful
});Updates the custom attributes for a specified receipt. For example, if a user purchases a "power up" and then uses it in a game, you can update the receipt to indicate that the product has been consumed and is not available for future sessions.
receiptId – String, unique identifier for the receipt.
attributes – Object, list of key-value pairs to update.
notificationMessage – String, (Optional) custom message to sent the user when the receipt is updated (up to 80 characters).
If undefined, the message will read: Your receipt for PRODUCT_NAME was updated.
(Async) Any, confirmation of the update, if the request was successful, or an error message, if not.
const receipt = await iap.updateReceipt(receiptId, { isConsumed: true }, 'Your power up has been used');An IapReceipt object represents a receipt for a user’s purchase of a product.
To determine whether a user has purchased a specific product, you can use resolveReceipts to retrieve the IapReceipt objects associated with the user’s token, and then look for a receipt with the product’s SKU.
The IapReceipt object includes the following properties.
|
Tip
|
Be sure to implement appropriate error handling to account for differences in object structure or empty values. |
{
id: string; (1)
userId: string; (2)
productId: string; (3)
purchasedPrice: number; (4)
attributes: { [index: string]: any }; (5)
datePurchased: Date; (6)
product?: IapProduct; (7)
transaction?: Transaction|null; (8)
transactionIds: { (9)
credit: string;
debit: string;
};
}id – Unique identifier for the receipt.
userId – Koji user name of the user who purchased the product.
The userId return value will always be unavailable.
To avoid leaking/fingerprinting users at a global level, Kojis must interact with users via a short-lived user token.
See getToken.
productId – Unique identifier for the product.
purchasedPrice – Price the user paid for the product.
attributes – Object containing a list of custom key-value pairs associated with the receipt.
You can use updateReceipt to update these values.
Additionally, the fulfillment information (email, phone, or address) and customMessage are included this object, if set at purchase time.
datePurchased – Date of the purchase.
product – IapProduct object that represents the purchased product.
transaction – Object that represents the transaction information, if available.
transactionIds – Object containing references to the associated transaction receipts – credit for the user receiving the funds (seller), debit for the user sending the funds (buyer).
To link to the transaction receipt in the user’s Koji wallet, use the format https://withkoji.com/payments/transactions/TXN_ID.
An IapProduct object represents a specific product for purchase.
Products are defined in the entitlements and registered or updated when the project is deployed.
You can use loadProduct to retrieve the properties associated with the product’s SKU.
The IapProduct object includes the following properties.
{
id: string; (1)
appId: string; (2)
ownerUserId: string; (3)
price: number; (4)
priceIsUnset: boolean; (5)
isConsumable: boolean; (6)
name: string; (7)
sku: string; (8)
dateCreated: Date; (9)
isActive: boolean; (10)
fulfillment?: 'email'|'phone'|'address'; (11)
quantity?: number; (12)
numAvailable?: number; (13)
owner?: UserArtifact; (14)
purchases?: IapReceipt[]; (15)
}id – Unique identifier for this version of the product.
appId – Name of the Koji from which the product was purchased.
ownerUserId – Koji user name of the creator.
price – Purchase price of the product.
Defined in the entitlements file of the template.
priceIsUnset – Indicator of whether a purchase price is defined for the product.
Defined in the entitlements file of the template.
isConsumable – Indicator of whether a product can be purchased more than once.
Defined in the entitlements file of the template.
name – Description displayed when the user was prompted to purchase the product.
Defined in the entitlements file of the template.
sku – Identifier of the purchased product.
Defined in the entitlements file of the template.
dateCreated – Date the product was registered or updated, which happens when the project is deployed.
isActive – Indicator of whether the product is still available for purchase.
fulfillment – Type of user information collected for order fulfillment.
Defined in the entitlements file of the template.
quantity – Total number of times the product can be sold (inventory threshold).
Defined in the entitlements file of the template.
numAvailable – Remaining number of times the product can be sold.
Calculated based on the total inventory defined in the entitlements file, less the number of purchases.
owner – Object that represents the template publisher ("seller").
purchases – Array of IapReceipt objects representing purchases of the product.
Core package replacement modules: IAP (backend), IAP (frontend)