VAPP

The VAPP! mobile payment SDK for Android

Getting Started

VAPP! is provided as a maven artefact. Your build.gradle file should then be modified so that it matches the code snippet below:

repositories {
    maven { url "https://jitpack.io" } // use Jitpack repository
}
dependencies {
    compile 'com.github.vasilitate:VAPP:v1.0' // add VAPP! SDK as a dependency
}

After syncing your gradle files, your project should be ready to initialise VAPP! with a list of products. See the sample application if you are having trouble with this step.

Vapp Numbers

You should download a 'vapp_numbers.csv' file and place it in your assets directory (/src/main/assets). This file can be found on the developer console under System > Profile > vapp_numbers.csv, and is required for the SDK to work.

Initialising VAPP!

Vapp.initialise() must be called before any SMS payments are made. Initialisation requires several pieces of information:

• Your SDK key, which identifies your payments for the app
• The number range which you have been assigned
• A list of products within your app, which can be paid for using SMS

It is recommended that you initialise VAPP! within a custom Application class, using something similar to the snippet below:

private static final String MY_SDK_KEY = "ABCDEFG123";

List<VappProduct> productList = new ArrayList<>();
List<VappProduct> subscriptionList = new ArrayList<>();

Vapp.initialise(this, productList, subscriptionList, false, false, MY_SDK_KEY);

Defining Products

Any products within your app must be passed into the SDK during initialisation. A VappProduct requires a unique alphabetic ID, the number of SMS messages which will be sent, and the maximum number of times that the product can be purchased.

private static final String MY_PRODUCT_ID = "MyProduct";
private static final int SMS_COUNT = 15;
private static final int MAX_PURCHASE_COUNT = 1;

List<VappProduct> productList = new ArrayList<>();
productList.add(new VappProduct.Builder(MY_PRODUCT_ID, SMS_COUNT).setMaxPurchaseCount(MAX_PURCHASE_COUNT).build());
Vapp.initialise(this, VAPP_APP_ID, productList, null, vappNumberRange, false);

Defining Subscriptions

Any subscriptions within your app must be passed into the SDK during initialisation. A VappProduct is used to define a subscription product and requires a unique alphabetic ID, the number of SMS messages which will be sent, the type of interval (either days, weeks or a given day of each month) and the interval. If the interval type is days, the interval gives the number of days between subscription renewals. Likewise if the interval type is weeks, the interval is the number of weeks between renewals. If the interval type is day of month, the interval is the day of the month to renew on (allowed values are 1 to 28).

private static final String MY_PRODUCT_ID = "MySubscription";
private static final int SMS_COUNT = 15;
private static final int SUBSCRIPTION_INTERVAL = 10;        // Ten days

List<VappProduct> subscriptionList = new ArrayList<>();
productList.add(new VappProduct.Builder(MY_PRODUCT_ID, SMS_COUNT).setSubscriptionIntervalType(SubscriptionIntervalType.DAY, SUBSCRIPTION_INTERVAL).build());
Vapp.initialise(this, VAPP_APP_ID, null, productList, vappNumberRange, false);

Notification Message

A notification will be displayed in the status bar once a purchase is complete. In order to change the text displayed, update the builder as below:

new VappProduct.Builder(MY_PRODUCT_ID, SMS_COUNT).setNotificationMessage("my custom message").build();

Purchasing Products

Products can be purchased by calling showVappPaymentScreen(). Before initiating the sale, you should indicate to the user what they are buying and how much it will cost, like below:

new AlertDialog.Builder(PaymentActivity.this)
      .setTitle("Confirm Payment")
      .setPositiveButton(android.R.string.ok, new DialogInterface.OnClickListener() {
          @Override public void onClick(DialogInterface dialog, int which) {
            Vapp.showVappPaymentScreen(context, MY_PRODUCT, false);
          }
      }).show();

Only one product may be purchased at a time. The SDK will enforce this however you should design your app so that it is obvious to the user that this is the case, e.g. by disabling purchasing options while one is in progress.

Tracking Purchases

The SMS purchase may take some time (10's of minutes!), callbacks are provided with the VappProgressReceiver:

@Override public void onCreate(@Nullable Bundle savedInstanceState) {
  super.onCreate(savedInstanceState)
  VappProgressReceiver vappProgressReceiver = new VappProgressReceiver(context, listener);
  vappProgressReceiver.onCreate();
}

@Override public void onDestroy() {
    super.onDestroy();
    if (vappProgressReceiver != null) {
        vappProgressReceiver.onDestroy();
        vappProgressReceiver = null;
    }
}

Progress Widget

You can make use of a purpose built progress view which allows you to display either the number of SMS's sent or the percentage completion as a progress bar and/or a numeric. Just add the following to your layout file:

    <com.vasilitate.vapp.sdk.VappProgressWidget
        android:id="@+id/progress_widget"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"/>

To get the following progress view displayed:

You can set the 'hideCount' or 'hideProgressBar' attributes on this widget in the layout file if you only which to display the progress bar or numeric respectively.

After referencing the widget in the code you can set it as the listener for the VappProgressReceiver as follows:

    VappProgressWidget progressWidget = (VappProgressWidget) findViewById( R.id.progress_widget);
 
    vappProgressReceiver = new VappProgressReceiver(this, progressWidget);
    vappProgressReceiver.onCreate();
    
    progressWidget.display(product, new VappProgressWidget.VappCompletionListener() {
            @Override
            public void onError(String message) { }

            @Override
            public void onErrorAcknowledged() { }

            @Override
            public void onCompletion() {
                progressWidget.setVisibility( View.INVISIBLE );
            }
        });

The widget also provides a VappCompletionListener listener to allow you to refresh the display once the purchase process has completed.

Purchase Status

It is also possible to determine whether a product has been purchased using synchronous methods. Your app can then allow the user access to purchased content, if VAPP! has recorded the product as purchased.

boolean hasPaid = Vapp.isPaidFor(context, MY_PRODUCT));
boolean isPaying = Vapp.isBeingPaidFor(context, MY_PRODUCT);

Cancelling Purchases

By default purchases are cancellable by the user. After clicking the cancel icon on the default Payment screen, the user will be prompted to confirm the cancellation. If you wish to disable this behaviour, set the cancellableProducts flag to false during Vapp.initialise(). It is also possible to manually cancel a purchase with the following code (which will prompt the user):

Vapp.cancelVappPayment(context);