Skip to content
This repository has been archived by the owner on Apr 3, 2020. It is now read-only.

A Possible IAP Web IDL

Jump to bottom
Deqing Huang edited this page Jun 27, 2014 · 7 revisions

1. Interface

interface window {
  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 {
  void init(key);
  Promise queryProductDetails(sequence<DOMString> products);
  Promise buy(DOMString id);
  Promise restore();
};

2.1 Methods

init

  • This method initialize the IAP plugin with a key that indicates a specific app. A plugin only handles products within one app at a time.
  • Parameter: key
  • Type: DOMString
  • Nullable: N
  • Optional: N

NOTE: Must call init() before calling all methods below.

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.
  • Parameter: products
  • Type: sequence<DOMString>
  • Nullable: N
  • Optional: N
  • Return type: Promise

buy

  • 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 buy 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 buy 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 orderId;
  attribute DOMString packageName;
  attribute DOMString productId;
  attribute DOMString purchaseTime;
  attribute DOMString purchaseState;
  attribute DOMString token;
}

4.1 Attributes

orderId of type DOMString

  • A string representing an unique order identifier for the transaction.

packageName of type DOMString

  • A string representing the application package from which the purchase originated.

productID of type DOMString

  • A string representing the purchased item's product identifier.

purchaseTime of type DOMString

  • A string representing the time of the product was purchased, in milliseconds since the epoch (Jan 1, 1970).

purchaseState of type DOMString

  • A string representing the purchase state of the order. Possible values are "purchased", "canceled", or "refunded".

5. API Examples

5.1 Initialize IAP plugin

For example, if this IAP is running on Android, then you need to go to developer's console to find out your application's key, and pass it to iap's init method. See Billing Security for details.

var key = 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsE'
iap.init(key);

5.2 Query product details

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

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.3 Buy an item

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

var id = 'gas';
iap.buy(id).then(
  function(result) {
    var orderId = result.orderId;
    var packageName = result.packageName;
    var productId = result.productId;
    var purchaseTime = result.purchaseTime;
    var purchaseState = result.purchaseState;

    var m = new Date(1970,0,1);
    m.setSeconds(purchaseTime/1000);
    var dateStringGMT =
      m.getUTCFullYear() +"/"+
      ("0" + (m.getUTCMonth()+1)).slice(-2) +"/"+
      ("0" + m.getUTCDate()).slice(-2) + " " +
      ("0" + m.getUTCHours()).slice(-2) + ":" +
      ("0" + m.getUTCMinutes()).slice(-2) + ":" +
      ("0" + m.getUTCSeconds()).slice(-2);

    document.getElementById("resultDiv").innerHTML += "Buy returned:"
      + "<br>Order ID: " + orderId
      + "<br>Package Name: " + packageName
      + "<br>Product ID: " + productId
      + "<br>Purchase Time(GMT): " + dateStringGMT
      + "<br>Purchase State: " + purchaseState;
  },
  function(error) { window.console.log('IAP purchase for ' + id + ' error: ' + error); } );

5.4 Restore previous transactions

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

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