Converting Android Apps into Android Add-ons | G Suite Add-ons

This guide describes how to convert an existing Android app to an Android add-on. If you are building an Android add-on from scratch, build it as a stand-alone Android app first, then follow these steps to make it an Android add-on.

If you're new to Android app development you may want to begin by following the Android Developer tutorial for Building Your First Android App.

Modify your Android manifest

Exposing add-on functionality from an existing Android app is as easy as adding an <intent-filter> to your app's Android manifest. In your app's manifest file , find the activity you’d like to expose as an add-on and add an <intent-filter> tag indicating your app can handle add-on intents, as demonstrated in this example:

<activity
    android:name="com.example.YourActivityName"
    android:label="@string/activity_name" >
    <intent-filter
        android:label="@string/addon_name"
        android:icon="@drawable/addon_icon">
        <action android:name="com.google.android.apps.docs.editors.sheets.ADDON" />
    </intent-filter>
</activity>
AndroidManifest.xml

Adding this intent-filter causes your add-on to be shown in the add-ons Menu in the Google Sheets app. You should provide an icon and label to be shown in the add-ons menu by specifying android:label and android:icon attributes for your intent filter (see Providing Resources and Accessing Resources from XML ).

To have your add-on extend Google Docs instead of Sheets, simply change the value of the <action> tag in the above example from:

"com.google.android.apps.docs.editors.sheets.ADDON"

"com.google.android.apps.docs.editors.docs.ADDON"

If your activity can extend both Docs and Sheets, include both <action/> tags in the intent-filter. Your add-on can determine at runtime which editor triggered it using your activity's getCallingPackage() method.

For more background on the intent-based mechanisms Android apps use to communicate, see Intents and Intent Filters.

Provide a default launcher activity

Most Android apps define a default launcher activity in their manifest. This activity is the first one started when the app is launched from the device's Home screen, and serves as the main entry point to the app.

Always include a launcher activity, even if launching your Android add-on on its own isn't useful. This handles cases when the add-on is launched directly, for example if a user taps the install notification.

If you are extending an existing Android app to be an Android add-on, chances are you already have a launcher activity. If you don't, be sure to create one. If the add-on functionality needs context from the Docs or Sheets apps to function at all, make a simple launcher activity that explains this to the user and provides a button to close the app.

Set Android permissions

Android add-on apps must have the GET_ACCOUNTS Android permission. This is necessary to allow your app to receive the Google account associated with the active document.

To request this permission, place the following tag in the <manifest> section of your app’s Android manifest. Many existing apps already request this permission.

<uses-permission android:name="android.permission.GET_ACCOUNTS" />

In addition, your add-on should also make use of runtime permissions when possible and follow the runtime permission best practices.

Modify your add-on activity

When a user selects your add-on from the Add-ons menu in a G Suite document editor, the activity specified in your manifest is started. In your activity’s onCreate method record the intent used to start your activity as it contains:

The document ID of the doc or sheet currently open in the editor app.
The session state of that doc or sheet (as an encoded String).
The account of the user calling the add-on.

You can get this intent by calling your activity’s getIntent() method. The resulting activity should resemble this example:

android/MyAddOnActivity.java

View on GitHub

import android.accounts.Account;
import android.app.Activity;

public class MyAddOnActivity extends Activity {
  // Your activity...

  String sessionState;
  String docId;
  Account account;

  @Override
  protected void onCreate(Bundle state) {
    super.onCreate(state);
    docId = getIntent().getStringExtra(
        "com.google.android.apps.docs.addons.DocumentId");
    sessionState = getIntent().getStringExtra(
        "com.google.android.apps.docs.addons.SessionState");
    account = (Account) getIntent().getParcelableExtra(
        "com.google.android.apps.docs.addons.Account");
    // Your activity’s initialization...
  }

  protected void makeRequest() {
        // Acquire the session state String from the calling Intent.
    sessionState = getIntent().getStringExtra(
        "com.google.android.apps.docs.addons.SessionState");
    // ...
    // Construct the API request.
    ExecutionRequest request = new ExecutionRequest()
            .setFunction(functionName)
            .setSessionState(sessionState)
            .setParameters(params)   // Only needed if the function requires parameters
            .setDevMode(true);       // Optional
  }
}

When your activity is finished and is ready to return the user back to the Google editor, set the result code and call your activity's finish() method, like so:

setResult(Activity.RESULT_OK);
finish();

Use document context with the Apps Script API

Most Android add-ons make use of Apps Script API to execute Apps Script functions. When using the API, including the session state ensures that Apps Script functions have the correct document context. With the document context, the API Script functions can call Apps Script methods normally restricted to calls from container-bound scripts. For example, passing context of a Google Doc enbles the called function to use DocumentApp.getActiveDocument().

In order to ensure the Apps Script API has the correct context when called from an Android app, you just have to include the session state string when building the ExecutionRequest object:

android/MyAddOnActivity.java

View on GitHub

protected void makeRequest() {
      // Acquire the session state String from the calling Intent.
  sessionState = getIntent().getStringExtra(
      "com.google.android.apps.docs.addons.SessionState");
  // ...
  // Construct the API request.
  ExecutionRequest request = new ExecutionRequest()
          .setFunction(functionName)
          .setSessionState(sessionState)
          .setParameters(params)   // Only needed if the function requires parameters
          .setDevMode(true);       // Optional
}

See the Apps Script API Android example for an example of how to call an Apps Script function from an Android app using the API.

Create OAuth credentials

Before your Android add-on can execute functions with the Apps Script API, you must enable the API in its associated Cloud Platform project. In addition, the add-on needs a valid Android OAuth credential, created using a SHA1 key.

You must properly sign any release build before uploading it to the Google Play Store, using a keystore you create and a key specific to that app. Because they depend on a different keystore, release builds need their own OAuth credential. This is built using the same steps used to create the debug build credential, except that you can get the SHA1 key using:

$ keytool -exportcert -alias <key_alias> -keystore <path_to_keystore_file> -list -v

This command asks you for the keystore password you set when you created the keystore (do not share this password with anyone).

Alternatively, you can also get the SHA1 keys for all your defined builds by running a signing report task from within Android Studio:

Click Gradle on the right side of the IDE window.
Navigate to MyApplication > Tasks > android and double-click signingReport.
To view the report, click Gradle Console at the bottom of the IDE window.

A Cloud Platform project can support multiple Android OAuth credentials, so you can create as many as you need.

Run your unpublished add-on

Only add-ons approved through the curation process are normally visible in the editors’ menus. During development a not-yet-reviewed add-on can be treated as though it were approved by setting the app as the system debug app. Once you have an Android device in developer mode and attached to a development machine via USB, you can set your app as the debug app by running the Android Debug Bridge command:

$ adb shell am set-debug-app --persistent <YOUR_PACKAGE_NAME>

This allows both debug and release builds of your add-on to run on your device.

The system debug app can be unset with:

$ adb shell am clear-debug-app