Google Play Install Referrer API

info

This chapter applies only if your app integrates with the Rubean Terminal app installed from Google Play. This feature is available from Rubean Terminal version 4.01.16.0207 and up.

After installing the Rubean Terminal app, the merchant is normally presented with a screen that asks for TID and password. If you use a different personalisation method, this can be confusing for the merchant.

Using the Google Play Install Referrer API, your app can provide redirect information before the Rubean Terminal app is installed.

The Rubean Terminal can redirect the merchant when the app is opened if both of the following conditions are met:

• The app is opened from Google Play or from the launcher.
• A Play Install Referrer value is present.

If the Rubean Terminal app is uninstalled and then reinstalled, Google removes the previous install referrer.

warning

To use this feature in the production Rubean Terminal app, please contact us first. Your packageId must be whitelisted in that environment.

How does the Google Play Install Referrer API work?

The Google Play Install Referrer API allows your app to pass information to the Rubean Terminal before it is installed. This is done by adding the referrer query parameter to the Google Play URL that opens the Rubean Terminal app listing.

Data format

info

The value of the referrer parameter is transported inside a URL and must be URL-safe. Please use Uri.Builder as shown below. If you can't use Uri.Builder, please minify the JSON and make sure the resulting string is also URL-safe.

The Rubean Terminal expects the referrer parameter to contain JSON in the following format:

{
  "redirectBeforePersonalisation": {
    "packageId": "string",
    "activity": "string"
  }
}

Requirements:

• packageId is required.
• activity is required and must contain the fully qualified activity class name.

If an empty object such as {}, an empty string, or invalid values for packageId or activity are provided, no redirect is executed.

Integration example

The integration consists of two parts:

1. Open the Google Play listing with the correct referrer value.
2. Export the callback activity that the Rubean Terminal should open afterward.

Installation with the right referrer variable

The following example shows how to open the Google Play listing of the Rubean Terminal app with an install referrer.

You can verify the received referrer value with this app: Install Referrer Test App It displays the referrer content that was attached during installation.

import android.content.Context;
import android.content.Intent;
import android.content.pm.PackageManager;
import android.net.Uri;

import androidx.annotation.NonNull;
import androidx.annotation.Nullable;

import org.json.JSONException;
import org.json.JSONObject;

public final class PlayReferrerSender {

    public enum TargetApp {
        RUBEAN_TERMINAL_PROD("com.rubean.phonepos.terminal"),
        RUBEAN_TERMINAL_QA("com.rubean.phonepos.terminal.qa"),
        INSTALL_REFERRER_TEST_APP("com.test.app.testinstallreferrer");

        private final String packageName;

        TargetApp(String packageName) {
            this.packageName = packageName;
        }

        public String getPackageName() {
            return packageName;
        }
    }

    private PlayReferrerSender() {
    }

    @NonNull
    private static String buildMinifiedReferrerJson(
        @Nullable String packageId,
        @Nullable String activity
    ) throws JSONException {
        JSONObject root = new JSONObject();

        if (packageId != null && activity != null) {
            JSONObject redirect = new JSONObject();
            redirect.put("packageId", packageId);
            redirect.put("activity", activity);
            root.put("redirectBeforePersonalisation", redirect);
        }

        // JSONObject#toString() returns compact / minified JSON.
        return root.toString();
    }

    @NonNull
    private static Uri buildPlayStoreUri(
        @NonNull TargetApp targetApp,
        @Nullable String redirectPackageId,
        @Nullable String redirectActivity
    ) throws JSONException {
        String minifiedJson = buildMinifiedReferrerJson(redirectPackageId, redirectActivity);

        return new Uri.Builder()
            .scheme("https")
            .authority("play.google.com")
            .path("store/apps/details")
            .appendQueryParameter("id", targetApp.getPackageName())
            .appendQueryParameter("referrer", minifiedJson) // The URI.Builder already handles url safe encoding for us
            .build();
    }

    /**
     *
     * @param context Application Context
     * @param targetApp The target app to install
     * @param redirectActivity The activity in your app that should be opened by the
     *                         Rubean Terminal when it is launched from Google Play or from the launcher.
     *                         Specify the fully qualified activity class name.
     * @throws JSONException From underlying JSON processing
     */
    public static void openPlayStore(
        @NonNull Context context,
        @NonNull TargetApp targetApp,
        @Nullable String redirectActivity
    ) throws JSONException {
        Uri playUri = buildPlayStoreUri(targetApp, context.getPackageName(), redirectActivity);

        Intent intent = new Intent(Intent.ACTION_VIEW, playUri);
        intent.setPackage("com.android.vending");
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);

        PackageManager pm = context.getPackageManager();
        if (intent.resolveActivity(pm) != null) {
            context.startActivity(intent);
        } else {
            // Fallback to generic browser / handler
            Intent fallback = new Intent(Intent.ACTION_VIEW, playUri);
            fallback.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
            context.startActivity(fallback);
        }
    }
}

Exporting the Callback Activity in the AndroidManifest

Create an activity that the Rubean Terminal can navigate to after installation. This activity must be enabled (which is true by default) and exported in your AndroidManifest.xml.

The simplest example is:

<activity
    android:name=".RedirectActivity"
    android:exported="true" />