The Catappult Developer Hub

Welcome to the Catappult developer hub. You'll find comprehensive guides and documentation to help you start working with Catappult as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Native Android SDK

This guide assumes that you have already Google Play billing integrated in your app. It will help you migrating from the Google Play to Catappult Billing service. Catappult billing service is implemented in a Wallet called "AppCoins Wallet". AppCoins wallet is widely available in different app stores. AppCoins Wallet exposes an Android Service which your app should bind with. Once bound to AppCoinsWallet service, your app can start communicating over IPC using an AIDL interface.

Google Play IAB to AppCoins IAB Migration Guide

Requirements

1. Catappult Public Key
Just like Google Play IAB, AppCoins IAB also exposes a public key. You should use AppCoins IAB public key to verify your purchases. It works exactly like Google Play IAB key, so you just need to replace one for the other.To find your Catappult public key, you should be registered in Catappult Back Office. You should head to Add App section of the BO and add the package name of your app (e.g. com.appcoins.wallet). Please make sure it's the same package name of the APK you'll upload later. Once you insert the package name and click "Next", you should already see your public key.

And change in your code:

       //Example key, use your own
       String base64EncodedPublicKey = "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAzZZoGzIM+TlYDyGWl78g37ChRtrUWCOTnF8Sy4zwC2vqQhI/QETkYM/jMruY3pLvdDOcdWm9xoZLJq5exxqQyhrZbSoziXQ9bIOJwNSjA/WIJnAewAk8QGPhvjNFy0wflCqLDWflrt04vbvvNsdh9UpgceIdinzqE0MhF94HJr1Ovb5JEMktDgU89SarCsx90a4Psk6cdapulGjdpL35dBRkRkM74sfNmSy8Oan9FaI36+z4h88MgTrELHnQ0XTlS32flvCK7nhICV+bzcY89wPRPN4rkqjS4F5nngwAnaz5VMV0Zy5SZBZntLS1QIA641FxJJHAikM8ZYz3hkTn0QIDAQAB";

Integration

1. On build.gradle

On allprojects you need to add the google and our maven repositories:

allprojects {
    repositories {
        google()
        jcenter()
        maven { url "https://dl.bintray.com/blockchainds/bds" }

    }
}

On the dependencies add the following lines

dependencies {
	<...other dependencies..>
  implementation 'com.blockchainds:appcoins-ads:0.5.1.32b'
  implementation 'com.blockchainds:android-appcoins-billing:0.5.1.32b'
  implementation 'com.blockchainds:appcoins-contract-proxy:0.5.1.32b'
}

2. Permissions
Your app needs a permission to allow it to perform billing actions with AppCoins IAB. The permission is declared in the AndroidManifest.xml file of your app. Since Google Play IAB already declares a permission with name com.android.vending.BILLING, you should rename it to com.appcoins.BILLING.

Google Play IAB

<uses-permission android:name="com.android.vending.BILLING" />

AppCoins IAB

<uses-permission android:name="com.appcoins.BILLING" />

3. Starting the Service Connection
The developer only needs to call startConnection on the billing sdk.
The SDK internally will check if the user has a wallet installed and carry on with the process and correct business logic.
If the wallet is installed the service will be initialised immediately and the billing state listener will be called. If not the user will be prompted to download the Appcoins Wallet, install it and setup a new wallet

String base64EncodedPublicKey = YOUR_KEY;
cab = CatapultBillingAppCoinsFactory.BuildAppcoinsBilling(this, base64EncodedPublicKey, purchasesUpdatedListener);
cab.startConnection(appCoinsBillingStateListener);

You need to pass a billing state listener to check the state of the billing service. This listener can be defined like this:

//First define your billing state listerner
AppCoinsBillingStateListener appCoinsBillingStateListener = new AppCoinsBillingStateListener() {
    @Override public void onBillingSetupFinished(int responseCode) {
      if (responseCode != ResponseCode.OK.getValue()) {
        complain("Problem setting up in-app billing: " + responseCode);
        return;
      }
      Log.d(TAG, "Setup successful. Querying inventory.");
    }

    @Override public void onBillingServiceDisconnected() {
      Log.d("Message: ", "Disconnected");
    }
  };

And you also need to use a PurchasesUpdatedListener to deal with the purchase result and consume the finished purchase

PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
      @Override public void onPurchasesUpdated(int responseCode, List<Purchase> purchases) {
      if (responseCode == ResponseCode.OK.getValue()) {
        String sku;
        for (Purchase purchase : purchases) {
          token = purchase.getToken();
          sku = purchase.getSku();

          switch (sku) {
            case Skus.YOUR_SKU_ID:
              cab.consumeAsync(token, consumeResponseListener);
              break;
            case Skus.OTHER_SKU_ID:
							...
							break;
          }
        }
      } else {
        complain("Error purchasing: " + String.format("response code: %d -> %s",
            responseCode, ResponseCode.values()[responseCode].name()));
        return;
      }
    };

The PurchasesUpdatedListener in turn needs a ConsumeResponseListener as shown bellow, to be able to consume the purchase.

ConsumeResponseListener consumeResponseListener = new ConsumeResponseListener() {
    @Override public void onConsumeResponse(int responseCode, String purchaseToken) {
      Log.d(TAG, "Consumption finished. Purchase: " + purchaseToken + ", result: " + responseCode);

      if (responseCode == ResponseCode.OK.getValue()) {

        Log.d(TAG, "Consumption successful. Provisioning.");

				//Your SKU logic goes here
      } else {
        complain("Error while consuming token: " + purchaseToken);
      }
      Log.d(TAG, "End consumption flow.");
    }
  };

When the setup finishes successfully you should immediately check for pending and/or owned purchases.

PurchasesResult purchasesResult = cab.queryPurchases(SkuType.inapp.toString());
List<Purchase> purchases = purchasesResult.getPurchases();

//Go through this list and check for owned premium skus

//Also check for pending skus that need to be consumed and consume them

     
     

4. Making a purchase
To make a purchase you just need to add the following code to the function that gets called when you press the buy button

Log.d(TAG, "Launching purchase flow.");
BillingFlowParams billingFlowParams =
        new BillingFlowParams(Skus.YOUR_SKU_ID, SkuType.inapp.toString(), //Your sku type
                              "orderId=" +System.currentTimeMillis(),
                              null,
                              null);

//Make sure that the billing service is ready
if (!cab.isReady()) {
  startConnection();
}

int response = cab.launchBillingFlow(this, billingFlowParams);

Afterwards in the onActivityResult you need to pass the result of the activity that contained the purchase flow to the *AppcoinsBillingClient* so the result of the purchase can be processed.
The following code snippet show how you can implement it:

  @Override protected void onActivityResult(int requestCode, int resultCode, Intent data) {
  	cab.onActivityResult(requestCode, resultCode, data);
  }

Testing

For testing purposes (before submitting to Catappult) you can use the following data to test the billing of you application.

  • applicationId:
    com.appcoins.sample
  • IAB_KEY: MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyEt94j9rt0UvpkZ2jPMZZ16yUrBOtjpIQCWi/F3HN0+iwSAeEJyDw7xIKfNTEc0msm+m6ud1kJpLK3oCsK61syZ8bYQlNZkUxTaWNof1nMnbw3Xu5nuYMuowmzDqNMWg5jNooy6oxwIgVcdvbyGi5RIlxqbo2vSAwpbAAZE2HbUrysKhLME7IOrdRR8MQbSbKEy/9MtfKz0uZCJGi9h+dQb0b69H7Yo+/BN/ayBSJzOPlaqmiHK5lZsnZhK+ixpB883fr+PgSczU7qGoktqoe6Fs+nhk9bLElljCs5ZIl9/NmOSteipkbplhqLY7KwapDmhrtBgrTetmnW9PU/eCWQIDAQAB

You can also get our version of Google's Trivial Drive with our billing implementation here to get your hands on an already working sample.

Known issues

  • AppCoins IAB is not compliant with Google Play IAB v5. Calls to getBuyIntentToReplaceSkus method will always fail.

User Acquisition

Catappult SDK Rewards (User Acquisition)

The Catappult SDK gives you the possibility to reward users with APPC Credits when your app is installed and used for two minutes.

Abstract

This tutorial will guide you through the process of adding the Catappult SDK as a dependency on your project.

The integration is simple enough to be completed in under 10 minutes. If this is not the case for you, let us know. The SDK can work in the main Ethereum network. You can still use the Ropsten test network, meaning that the APPC don' have real monetary value, they are used solely for testing purposes.

Prerequisites

  • In order for the SDK to work, you must have an AppCoins compliant wallet installed.
  • Minimum gradle plugin version is 3.0.1.
  • Minimum build tools version is 26.0.1.
  • The Android minimum API Level to use SDK is 16 (Android 4.1).
  • Basic understanding of RxJava is not required but is recommended.

Note: When used in devices with Android OS version 4.4 or lower, the user will not be able to install the AppCoins Wallet that only supports minimum SDK 21.

Build Script

In your project's buildscript, make sure you have the following:

buildscript {
  repositories {
    jcenter()
    google()
  }
  dependencies {
    classpath 'com.android.tools.build:gradle:3.1.0'

    // NOTE: Do not place your application dependencies here; they belong
    // in the individual module build.gradle files
  }
}

allprojects {
  repositories {
    jcenter()
    google()
    maven { url "https://dl.bintray.com/blockchainds/bds" }
  }
}

And in your app's buildscript, add the following dependency:

dependencies {
    api 'com.blockchainds:appcoins-ads:0.5.1.31b'
}

As an example, every time there is an update of the SDKs where no further integration needs to be done, the only thing that should be changed is the version. For example, when the next version is released, the dependencies that should be included in the app's buildscript are:

dependencies {
    api 'com.blockchainds:appcoins:0.5.1.31b'
}

Getting Started

To integrate the User Acquisition SDK, you only need to create an instance of the AdsSdk interface.

In the sample code, we create an instance of the User Acquisition SDK interface in the Application class . Afterwards you only need to initialize the Proof-of-Attention (PoA) process.

  private static AppCoinsAds adsSdk;

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

    adsSdk = new AppCoinsAdsBuilder()
        .createAdvertisementSdk(this);
    try {
      adsSdk.init(this);
    } catch (PackageManager.NameNotFoundException e) {
      e.printStackTrace();
    }
  }

Please note that the calling of the init() is required to be done as soon as possible. For that reason, we recommend doing it on the onCreate() of the Application class so the SDK is aware of the application's Activities life cycle.

After the SDK configuration and initialization, and as soon as any Activity or your application is started, the SDK will be able to detect whether your application is in the foreground and will handle the Proof-of-Attention (PoA) process.

Size

As of version 0.4.7.21b, SDK weight is approximately as follows:

  • SDK aar only - 35.51KB.

App size increase after adding sdk (assuming no dependencies in common):

  • Without Proguard: 4.9MB.
  • With Proguard: 2.6MB.

Native Android SDK


This guide assumes that you have already Google Play billing integrated in your app. It will help you migrating from the Google Play to Catappult Billing service. Catappult billing service is implemented in a Wallet called "AppCoins Wallet". AppCoins wallet is widely available in different app stores. AppCoins Wallet exposes an Android Service which your app should bind with. Once bound to AppCoinsWallet service, your app can start communicating over IPC using an AIDL interface.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.