A Possible Web IDL for IAP

1. Navigator interface

partial interface Navigator {
    readonly    attribute InAppPurchase iap;
};

1.1 Attributes

iap of type InAppPurchase, readonly

• The object that exposes the In App Purchase functionality.

2. InAppPurchase interface

The InAppPurchase interface exposes the In App Purchase functionality.

interface InAppPurchase {
  Promise queryProductDetails(sequence<DOMString> products);
  Promise purchase(DOMString id);
  Promise restore();
};

2.1 Methods

queryProductDetails

• This method allows to query details of available products from payment provider. It returns a Promise that will allow the caller to be notified about the result of the operation.
• Type: sequence<DOMString>
• Nullable: N
• Optional: N
• Return type: Promise

purchase

• This method allows to buy an available product from payment provider. It returns a Promise that will allow the caller to be notified about the result of the operation.
• Parameter: id
• Type: DOMString
• Nullable: N
• Optional: N
• Return type: Promise

restore

• This method allows to restore transactions of current user which already been finished. It returns a Promise that will allow the caller to be notified about the result of the operation.
• No parameters.
• Return type: Promise

2.2 Method Procedures

The queryProductDetails method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver its associated resolver.
2. Return promise and continue the following steps asynchronously.
3. Make a request to the system to retrieve details of the available products which indicated by an array of product IDs.
4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
5. When the request has been completed:

• Let products be a new array of IAPProduct objects providing the results of the queryAvailableProducts operation.
• Invoke resolver's fulfill algorithm with products as the value argument.

The purchase method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver its associated resolver.
2. Return promise and continue the following steps asynchronously.
3. Make a request to the system to purchase a product which indicated by the id parameter.
4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
5. When the request has been completed:

• Let transaction be the IAPTransactionDetails object as returned by the system.
• Invoke resolver's fulfill algorithm with transaction as the value argument.

The restore method when invoked MUST run the following steps:

1. Let promise be a new Promise object and resolver its associated resolver.
2. Return promise and continue the following steps asynchronously.
3. Make a request to the system to restore transactions of current user which already been finished.
4. If there is an error invoke resolver's reject algorithm with no argument and terminate these steps.
5. When the request has been completed:

• Let transactions be an array of IAPTransactionDetails objects as returned by the system.
• Invoke resolver's fulfill algorithm with transactions as the value argument.

3. IAPProduct interface

The IAPProduct interface represents a product's attributes and the types associated to it.

interface IAPProduct {
  attribute DOMString id;
  attribute DOMString price;
  attribute DOMString title;
  attribute DOMString type;
  attribute DOMString description;
}

3.1 Attributes

id of type DOMString

• Represents a unique identifier of the product.

price of type DOMString

• A string representing the product's price (might include its currency information).

title of type DOMString

• A string representing the product's title.

type of type DOMString

• A string representing the product's type (e.g. "consumable", "non-consumable", "subscription")

description of type DOMString

• A string describes the product.

4. IAPTransactionDetails interface

The IAPTransactionDetails interface represents a transaction's attributes.

interface IAPTransactionDetails {
  attribute DOMString id;
  attribute date time;
  attribute DOMString token;
}

4.1 Attributes

id of type DOMString

• A string representing an unique identifier of the transaction.

time of type date

• A date element representing the transactions issue time.

token of type DOMString

• A string that uniquely identifies a purchase for a given item and user pair.

5. API Examples

5.1 Query product details

User wants to know details of products that are available for purchasing.

navigator.iap.queryProductDetails(["gas", "tyre", "accelerator"]).then(
  function(products) {
    for (var i=0; i<products.length; i++) {
      console.log("ID: " + products[i]["productId"]);
      console.log("Price: " + products[i]["price"]);
      console.log("Currency: " + products[i]["price_currency_code"]);
      console.log("Title: " + products[i]["title"]);
      console.log("Description: " + products[i]["description"]);
    }
  },
  function(error) { window.console.log('IAP queryProductDetails() error: ' + error); } );

5.2 Purchase an item

User wants to buy an item, and would like to know when the transaction is done.

var id = 'gas';
navigator.iap.purchase(id).then(
  function(transaction) { window.console.log('Successfully brought ' + transaction.id + ' at ' + transaction.time); },
  function(error) { window.console.log('IAP purchase for ' + id + ' error: ' + error); } );

5.3 Restore previous transactions

User wants to restore all his/her finished transactions, and would like to know how many transactions are restored.

navigator.iap.restore().then(
  function(transactions) { window.console.log('Successfully restored ' + transactions.length + ' transactions.'); },
  function(error) { window.console.log('IAP purchase for ' + id + ' error: ' + error); } );