`buildfire.services.commerce.inAppPurchase`

IAP (In App Purchases) allows the user to gain access to premium digital content or features. Both iOS and Android supports IAP.

Check links below for more info:

If you haven't setup your app for In App Purchases in buildfire or have not yet added any products go through the following links first:

note

Testing purchases only works on a mobile device.

Notes for Android

For testing purchases the build must be a release build and installed from Google Play Store (Alpha, Beta or Production).
Only testers added in your Google Play Store account can test purchases without requiring a real payment to be processed.
The Google Play Store account user cannot be an IAP tester or have the account user linked on testing devices.

Notes for iOS

For testing purchases the build must be downloaded from TestFlight.

Requirements

Include inAppPurchase.js file in widget header right after the buildfire.min.js

<head>
  <!-- ... -->
  <script src="../../../scripts/buildfire.min.js"></script>
  <script src="../../../scripts/buildfire/services/commerce/inAppPurchase.js"></script>
</head>

Control

Include inAppPurchase.js file in control header right after the buildfire.min.js

<head>
  <!-- ... -->
  <script src="../../../../scripts/buildfire.min.js"></script>
  <script src="../../../../scripts/buildfire/services/commerce/inAppPurchase.js"></script>
</head>

Methods

`getProducts()`

buildfire.services.commerce.inAppPurchase.getProducts(callback)

Fetches a list of products, defined in the buildfire control panel.

buildfire.services.commerce.inAppPurchase.getProducts((err, products) => {
  if (err) return console.error(err);

  console.log('In app purchase products', products);
});

`callback(err, products)`

Callback function called when products are fetched. Might get error if called too early before InAppPurchase initializes.

Name	Type	Description
`err`	string	error string, `null` when operation is successful
`products`	[object]	Array of products available

`product`

Each product has the following properties, as defined in the control panel.

Name	Type	Description
`id`	string	Unique, randomly generated identifier
`name`	string	Display name, assigned in the control panel
`platformProductId`	string	Unique identifier, assigned to the product when it is created on Apple or Android platform
`tag`	string	Tag assigned to a user when they purchase a product.

`getSubscriptions()`

buildfire.services.commerce.inAppPurchase.getSubscriptions(callback)

Fetches a list of subscriptions, defined in the buildfire control panel.

buildfire.services.commerce.inAppPurchase.getSubscriptions((err, subscriptions) => {
  if (err) return console.error(err);

  console.log('In app purchase subscriptions', subscriptions);
});

`callback(err, products)`

Callback function called when subscriptions are fetched. Might get error if called too early before InAppPurchase initializes.

Name	Type	Description
`err`	string	error string, `null` when operation is successful
`subscriptions`	[object]	Array of subscriptions available

`subscription`

Each subscription has the following properties, as reflected in the control panel.

Name	Type	Description
`id`	string	Unique, randomly generated identifier
`name`	string	Display name, assigned in the control panel
`platformProductId`	string	Unique identifier, assigned to the product when it is created on Apple or Android platform
`tag`	string	Tag assigned to a user when they purchase a subscription.

`purchase()`

buildfire.services.commerce.inAppPurchase.purchase(productId, callback)

Initiates a purchase request.

buildfire.services.commerce.inAppPurchase.purchase('m1eo1i1e91da2si2d12', (err, result) => {
  if (err) return console.error(err);

  console.log('Purchase request result', result);
});

`productId`

Id assigned to the product. Note that this ID is not the Google Play product ID, or the iOS product ID. It is an auto generated id that can be retrieved using getProducts function.

Name	Type	Required	Description	Default
`productId`	string	yes	Id assigned to the product. Note that this ID is not the Google Play product ID, or the iOS product ID. It is an auto generated id that can be retrieved using `getProducts` function.

`callback(err, result)`

Callback function executed when purchase request is completed. May not be called if user leaves the purchase. Returns the result of the purchase request, if successful (the request, not the purchase itself).

Name	Type	Description
`err`	string	error string, `null` when operation is successful
`result`	object	Object containing purchase result details

`result`

Name	Type	Description
`product`	object	Product object
`isApproved`	boolean	Indicates if payment is approved
`hasErrors`	boolean	Indicates if payment error happened
`isCancelled`	boolean	Indicates if payment was cancelled

`checkIsPurchased()`

buildfire.services.commerce.inAppPurchase.checkIsPurchased(options, callback)

Checks if a product or subscription has been purchased. In addition, this will check if a subscription is expired or invalid.

const options = { productId: 'm1eo1i1e91da2si2d12', type: 'subscriptions' };

buildfire.services.commerce.inAppPurchase.checkIsPurchased(options, (err, isPurchased) => {
  if (err) return console.error(err);

  console.log('Item Purchased:', isPurchased);
});

`options`

Name	Type	Required	Description	Default
`productId`	string	yes	Id assigned to the product. Note that this ID is not the Google Play product ID, or the iOS product ID. It is an auto generated id that can be retrieved using `getProducts` function.
`type`	string	no	Determines the type of purchase to check for (subscriptions or product).	`product`

`callback(err, result)`

Callback function executed when the request is complete. Returns ownership state as a boolean.

Name	Type	Description
`err`	string	error string, `null` when operation is successful
`result`	boolean	Returns true if the product has been purchased. Returns false if the product is not purchased, a subscription is expired, or any purchase is invalid.

Events

`onPurchaseRequested()`

buildfire.services.commerce.inAppPurchase.onPurchaseRequested(callback, allowMultipleHandlers)

Executes the callback when a purchase is requested.

buildfire.services.commerce.inAppPurchase.onPurchaseRequested(product => {

  console.log(`Purchase requested for ${product.type}: ${product.productId}`);
  // ex: "Purchase requested for subscription: monthly_premium"
});

`options`

Name	Type	Required	Description	Default
`callback`	function	yes	Callback to be executed when a purchase is requested.
`allowMultipleHandlers`	boolean	no	Overrides all other handlers is set to false (default), or allow multiple handlers to exist at the same time if true.	false

`callback(product)`

Callback function executed when a purchase is requested.

Name	Type	Description
`product.productId`	string	Id assigned to the product. Note that this ID is not the Google Play product ID, or the iOS product ID. It is an auto generated id that can be retrieved using `getProducts` function.
`product.type`	string	The type of purchase requested (subscriptions or product).

`onPurchaseResult()`

buildfire.services.commerce.inAppPurchase.onPurchaseResult(callback, allowMultipleHandlers)

Executes the callback when a purchase is completed. Provides the result of the purchase in the callback.

note

This event is executed regardless of the result of the purchase. Check for product.result to determine ownership state!

buildfire.services.commerce.inAppPurchase.onPurchaseResult(product => {

  console.log(`Purchase result for ${product.type}: ${product.productId}. Order was ${product.result}`);
  // ex: "Purchase result for subscription: monthly_premium. Order was canceled"
});

`options`

Name	Type	Required	Description	Default
`callback`	function	yes	Callback to be executed when a purchase is requested.
`allowMultipleHandlers`	boolean	no	Overrides all other handlers if set to false (default), or allow multiple handlers to exist at the same time if true.	false

`callback(product)`

Callback function executed when the purchase is complete. Returns the result of the purchase.

Name	Type	Description
`product.productId`	string	Id assigned to the product. Note that this ID is not the Google Play product ID, or the iOS product ID. It is an auto generated id that can be retrieved using `getProducts` function.
`product.type`	string	The type of purchase requested (subscriptions or product).
`product.result`	string	The result of the order (success, canceled, or failed)

`product.result`

The result of the purchase.

Name	Type	Description
`success`	string	Purchase was sucessful.
`canceled`	string	User canceled the purchase, and was not charged.
`failed`	string	An error occured during purchase.

buildfire.services.commerce.inAppPurchase

Requirements​

Widget​

Control​

Methods​

getProducts() ​

callback(err, products)​

product​

getSubscriptions() ​

callback(err, products)​

subscription​

purchase() ​

productId​

callback(err, result)​

result​

checkIsPurchased() ​

options​

callback(err, result)​

Events​

onPurchaseRequested() ​

options​

callback(product)​

onPurchaseResult() ​

options​

callback(product)​

product.result​

`buildfire.services.commerce.inAppPurchase`

Requirements

Widget

Control

Methods

`getProducts()`

`callback(err, products)`

`product`

`getSubscriptions()`

`callback(err, products)`

`subscription`

`purchase()`

`productId`

`callback(err, result)`

`result`

`checkIsPurchased()`

`options`

`callback(err, result)`

Events

`onPurchaseRequested()`

`options`

`callback(product)`

`onPurchaseResult()`

`options`

`callback(product)`

`product.result`