Skip to content

Payments: In App Purchases SDK

Jump to bottom
paulotrezentos edited this page Oct 16, 2018 · 1 revision

Gitter chat

IAP Use Case Artefacts Protocol Base

Below is the diagram of the IAP use case with the necessary artefacts and interactions between them, which enable users to effectively pay for in-app items using APPC.

The artefacts from the AppCoins Project used in the IAB use case are:

Create SKUs Protocol Base

While developing an app and integrating the App Store Foundation (ASF) SDK, the developer should create the SKUs and manage them inside the app. Since ASF is agnostic of third parties and is focused in developing the reference implementation of the AppCoins Protocol, there is no backend for managing SKUs and purchases. This means that both the definition and management of SKUs should be done inside the app and the ASF SDK.

You can check out the detailed guide to integrate the ASF SDK in its official documentation, but the interface to create SKUs is shown below.

  public static AppCoinsIab appCoinsSdk;

  private final String developerAddress = "0x4fbcc5ce88493c3d9903701c143af65f54481119";

  @Override public void onCreate() {
    super.onCreate();

    appCoinsSdk = new AppCoinsIabBuilder(developerAddress).withSkus(buildSkus())
        .withDebug(true)
        .createAppCoinsIab();
  }

  private List<SKU> buildSkus() {
    List<SKU> skus = new LinkedList<>();

    skus.add(new SKU(Skus.SKU_GAS_LABEL, Skus.SKU_GAS_ID, BigDecimal.valueOf(1)));
    skus.add(new SKU(Skus.SKU_PREMIUM_LABEL, Skus.SKU_PREMIUM_ID, BigDecimal.valueOf(2)));

    return skus;
  }

After the integration of the ASF SDK, the app should be built and uploaded to the App Stores of choice of the developer. The in-app billing management done by the ASF SDK works the same way in any App Store that integrates with the AppCoins Protocol.

Artefacts used:

Upload APK Protocol Base

After integrating the ASF SDK, the developer should upload the resulting APK to an app store that integrates the AppCoins Protocol. The APK can be uploaded to one or several app stores, as it will work the same. The APK can be uploaded to an app store that is not compliant with the AppCoins Protocol, as the IAB flow will still work. However, the revenue share allocated to the app store will not go to any.

Show impressions Protocol Base

Once the developer uploads the app to an app store, the latter should show it to users to foster the AppCoins Protocol adoption. Since the app store earns a share of each in-app purchase, it has the incentive to increase the protocol's adoption.

Install App / Broadcasts ETH addresses of app store and OEM Protocol Base

Artefacts used:

Initiate payment Protocol Base

When a user clicks in an in-app item to buy it, the ASF SDK interacts with the ASF Wallet for the payment to take place. The interface in the ASF SDK to start a payment in the ASF Wallet is the following:

appCoinsSdk.buy(SKU_GAS, this).subscribe(() -> {
      // In this case the buy process was triggered as expected.
}, throwable -> {
      // There was an error triggering the buy process.
});

This method abstracts the developer from the communication between the SDK and the Wallet, which is implemented while being (fairly) compliant with the EIP681 (approved at DevCon3, so now ERC681). The adaptation of EIP681 to the AppCoins ecosystem is called in this documentation EIP681A and is defined here.

Artefacts used:

Perform payment transaction Protocol Base

Once in the ASF Wallet, the user will be able to pay using APPC for the chosen in-app item. The ASF Wallet use the approve + buy pattern to perform the payment in the Blockchain.

These methods are coded in two different smart contracts that are included in the AppCoins Protocol:

  • The approve method is implemented in the AppCoins token smart contract
  • The buy method is implemented in the IAP smart contract

The approve method is used when someone wants to give access to a certain amount of funds to someone else. It has the following signature:

function approve(address _spender, uint256 _value) public returns (bool success)

Therefore, when called, the caller of the approve method allows the _spender to have access to the _value of APPC and use it has needed. In this case, since it is the IAP smart contract that will do the revenue split to the developer, app store and OEM when an in-app purchase occurs and actually does the transfers, the user needs to give it access to the amount of APPC the in-app item costs. This approve transaction is sent to the Blockchain and signed by the user's wallet.

As an example, assuming a purchase of an in-app item costing 10 APPC and the current address of the IAP smart contract being 0xb015D9bBabc472BBfC990ED6A0C961a90a482C57, the approve method would be called with the signature:

approve(0xb015D9bBabc472BBfC990ED6A0C961a90a482C57, 1000000000000000000)

where 1000000000000000000 is the value in Wei of the 10 APPC.

The ASF Wallet then calls the buy method in the IAP smart contract, which sends an event containing the transaction data to the Blockchain, which can be verified by anyone. The buy method has the following signature:

function buy(uint256 _amount, string _sku, address _addr_appc, address _dev, address _appstore, address _oem) public view returns (bool)

The caller informs the protocol that the _sku_ was bought for _amount APPC and the revenue should be split by the developer, app stores with the addresses _dev, _appstore and _oem, respectively.

The event is sent and the revenue split of the purchase is done, with 85% being sent to the developer, 10% to the app store and 5% to the OEM, as it is described in the technical whitepaper. The transfer of these amounts is done by the IAP smart contract in the name of the user calling the buy method. The smart contract can move those funds because previously it was given permission by the user with the approve method.

Artefacts used:

Clone this wiki locally