API Guide

Preparing your mini app Activity

A mini app needs an Activity class to display your app content inside the side screen. To prepare the mini app, lets first create a new activity. Create a new activity in your project, as you normally would, and extend it to TooleapActivities.Activity, instead of the normal Activity class.

For example, let’s create a new Activity called “MyTooleapActivity”:

The TooleapActivities.Activity class acts just like any normal Activity. You can add a content view to this Activity just like you would in any Activity, and you can count on the Activity lifecycle being called (onCreateonResumeonPause etc…).

Note: In this tutorial we are extending a regular Activity class, but Tooleap support different types of Activity classes, and even popular third party activity classes such as ActionBarShelock. See Tooleap Activities for more info.

Next we’ll add the Tooleap Activity declaration to your app’s AndroidManifest.xml file:

 

Setting a Theme

The android:theme property in the Activity declaration inside the AndroidManifest.xml file must be set to Theme.Translucent (or one of its descendants like Theme.Translucent.NoTitleBar).

Note: To remove the grey title bar from your mini app, use Theme.Translucent.NoTitleBar.

To work with themes add a meta data tag to the Activity declaration in the manifest as follows:

Alternatively, you can call setTheme() in your activity, with the theme resource id of your choice. Note that this should be called before any views are instantiated in the Context (for example before calling setContentView(View)).

 

Screen Rotation Support

To support screen rotation, even while the side-screen is opened on top of non-rotating apps (like the home screen), add android:screenOrientation=“user” to your activity declaration in the manifest as follows –

 

Using an Existing Activity

Instead of creating an Activity from scratch, you may want to use one of the activities already existing in your application, to be used in a mini app. Using an existing activity is very easy, and similar to creating a new one. First, extend your existing Activity class (“MyActivity”) to use TooleapActivities.Activity (or any other appropriate TooleapActivitiesclass).

You can still use your existing activity (in our example “MyActivity”) regularly as you did before – Tooleap SDK won’t change the flow, or add any extra code to your Activity.

Next, create a new empty Activity, that extends your existing activity:

Finally, add your new activity to the manifest, as already described before:

Now you can use the same existing Activity both as a regular Activity (just like before) and as a Tooleap Activity of a mini app.

Note: If you want your activity to behave differently when it appears in a mini app, you can use the isStartedByTooleap() method defined in Tooleap Activity classes. For more info see Tooleap Activities.

To display a mini app, create an intent with the Tooleap Activity of your mini app. You can customize the intent as you would with any intent, and pass extra data:

Create a new mini app object, and customize its properties to your liking. In the following example we’ll use a “PopOut” mini app. You can learn more about other types of mini apps in Mini App Types section.

Now you can display the mini app using the addMiniApp method:

The SDK allows you to control some of the properties of the bubble and your mini apps.

For example, you can set the title of the mini app as follows:

Note: You can customize a mini app visual prior to calling the addMiniApp method. If you need to update your mini app visual style use updateMiniApp as explained in Manage Your Mini Apps section.

 

Bubble Customization Guide
Figure 1. The Bubble that includes the [1] app icon, [2] bubble background, [3] notification badge and [4] the notification text balloon.

Sidebar Customization Guide
Figure 2. The title bar that includes the [1] app icon, [5] content title and [6] the dismiss button.

 

Mini App Customization Guide

Figure 3. The bottom bar that includes the [1] app icon and the [3] notification badge.

Mini App Customization Guide

Figure 4. The menu that includes the [1] app icon, [3] notification badge, [5] content title, [7] content text, [8] when the mini app was added and the [6] dismiss button.

Bubble and Mini App Display Elements

#

Name

Fields / Methods

Notes

1

Icon

TooleapMiniApp.setIcon(Context context, int resourceId)
TooleapMiniApp.setIcon(byte[] icon)
TooleapMiniApp.setIcon(Bitmap icon)

If no icon is specified, the default application icon is used. An icon of at least 30dp x 30dp is recommended

2

Bubble Background Color

TooleapMiniApp.bubbleBackgroundColor

The Bubble’s background color is in ARGB format (e.g 0x99AAFFCC)

3

Notification Badge Number

TooleapMiniApp.notificationBadgeNumber

Once a user views a mini app with that has a visible notification badge, the SDK automatically clears the badge, and resets its value to 0

4

Notification Text

TooleapMiniApp.notificationText

5

Content Title

TooleapMiniApp.contentTitle

6

Dismiss button

TooleapPersistentMiniApp.allowUserToDismiss(boolean isDismissible)
TooleapHomeMiniApp.allowUserToDismiss(boolean isDismissible)

Can only be customized in Persistent or Home mini apps. See Mini App Types guide

7

Content Text

TooleapMiniApp.contentText

8

When the mini app was added

TooleapMiniApp.when

Managing your mini app is done using your mini app id. The addMiniApp method returns a mini app id which you can keep in order to later modify or delete your mini app:

The SDK enables you to manage your existing mini apps using the following methods:

Get:

Update:

The updateMiniAppAndNotify method updates the mini app fields and then pops out the bubble from the edge of the screen, so that the change will be brought to the user’s attention. Useful if you added a notification text to the bubble, and you want the user to notice it.

Remove:

Notice: removing a mini-app does not finish the mini app Activity
 
Here is an example that displays a badge and a notification text for an existing mini app:

 

Tooleap SDK supports several types of mini apps:

  • Notification Mini App – Use this mini app to display a rich notification, and allow the user to interact with your app, directly from the side screen.
  • PopOut Mini App – Appropriate when you want to give your users the ability to pop out a screen from your app, so they’ll use it along other applications.
  • Persistent Mini App – An always-available mini app. Use this mini app to give your user access to your app screen from anywhere on his device.
  • Home Mini App Combine the availability of Android Home Screen Widgets, with the ease of development of a regular activity screen. Have a mini app available exclusively from your user’s home screen.

All the different mini app types are managed the same. You can set their properties, add, update and remove them. They are different in their default properties values, and some special features each of them offers. The different mini apps are sub-classes of TooleapMiniApp class. Every method that accepts the TooleapMiniApp class, can accept any one of them.

 


 Notification Mini App


Use this mini app to display a rich notification, and allow the user to interact with your app, directly from the side screen.

For example, a messaging app can pop out a rich notification. The user sees the bubble with the preview text of the notification, and replies the message right from the side screen.

Default property values:

  • Notification Badge Number = 1

Usage:

 


 PopOut Mini App


Appropriate when you want to give your users the ability to pop out a screen from your app, so they’ll use it along other applications.

For example, a music app that allows the user to pop out its playback controls, so they will be only one tap away, even while using other apps.

Default property values:

  • None

Usage:

 


 Persistent Mini App


An always-available mini app. Use this mini app to give your user access to your app screen from anywhere on his device.

For example, a news app that gives its users an always quick access to its headlines, on top any application currently being used.

Default property values:

  • None

Special properties

  • Non-Dismissible – By default, persistent mini apps can’t be dismissed by the user. To allow the user to dismiss them, use allowUserToDismiss(boolean isDismissible) method in TooleapPersistentMiniApp class.
  • Starts at Device Reboot – Persistent mini app will be available to the user even after device reboot. Note that the application needs to be installed on the device SD card in order to start at device reboot.
  • Contextuality – By default, the persistent mini app bubble float over every application on your device. You can set the persistent mini app to appear only over specific applications. we’ll cover it in the Contextuality guide.

Usage:

Add to your AndroidManifest.xml file the following permission:

Add to your AndroidManifest.xml file the  BOOT_COMPLETED intent action under the TooleapReceiver tag, so it should look like this:

 


 Home Mini App


Combine the availability of Android Home Screen Widgets, with the ease of development of a regular activity screen. Have a mini app available exclusively from your user’s home screen.

For example, a weather app that allows its user to check today’s weather, without cluttering his home screen with an extra widget.

Default property values:

  • None

Special properties

  • Non-Dismissible – By default, home mini apps can’t be dismissed by the user. To allow the user to dismiss them, use allowUserToDismiss(boolean isDismissible) method in TooleapHomeMiniApp class.
  • Starts at Device Reboot – Home mini app will be available to the user even after device reboot. Note that the application needs to be installed on the device SD card in order to start at device reboot.
  • Home Screen Contextuality – The mini app bubble will appear only on top of the device home screen.

Usage:

Add to your AndroidManifest.xml file the following permission:

Add to your AndroidManifest.xml file the BOOT_COMPLETED intent action under the TooleapReceiver tag, so it should look like this:

 

Mini App Types Comparison Table  


 

Notification

PopOut

Persistent

Home

Is Dismissible

Yes

Yes

No (Default)

No (Default)

Notification Badge

Shown with a value of “1” (Default)

None (Default)

None (Default)

None (Default)

Starts at Device Reboot

No

No

Yes

Yes

Contextuality

Yes

Only shown at home screen

Your mini app uses a Tooleap Activity as its content, displayed inside the side screen. Tooleap supports a wide variety of Activity class types. All Tooleap Activities are sub-classes of Android’s regular Activity class, with an extra ability to be displayed inside the side screen. In fact, you can even use the Tooleap Activity both for your regular app screen and for the Tooleap side screen, as explained in Create a Mini App section. Tooleap SDK supports all types of standard Activity classes, as well as Android support library Activities and popular third party packages such as ActionBarSherlock. You can access all Tooleap Activities from the TooleapActivities class. For a full list of supported Tooleap Activities see our API Reference.

For example, to create a Tooleap Activity based on the FragmentActivity class, use:

All Tooleap Activities extend their base Activity class with the following methods:

  • isStartedByTooleap() – Use this method when you want to distinguish if this activity was started by Tooleap, meaning it is being currently displayed as a mini app’s content inside the side screen. Returns true if this Activity was started by Tooleap.
  • getTooleapAppId() – Get the mini app id of the mini-app currently using this Tooleap Activity.

 Using startActivityForResult

Android allows you to start an activity from another activity and receive a result back, as depicted here. In order for it to work properly with Tooleap Activities, add the following activity declaration to the AndroidManifest.xml file:

 

The NotificationHelper class allows you to easily display notifications for existing mini apps. Call the buildNotification method to start building your notification, and after you are done setting the notification fields, call the buildAndNotify() method. The bubble will pop out from the edge of the screen, and display your notification:

Note: Using the notification helper is the same as calling updateMiniAppAndNotify.

 

Get notified when the user removes a mini-app

The Tooleap SDK broadcasts USER_REMOVED_MINI_APP every time a user removes a mini-app (by pressing on the ‘X’ button, or dragging the floating bubble to the ‘X’ drop-zone).

You can listen to that broadcast, extract the removed mini-app id, and act accordingly. For example:

Note that both the APP_ID parameter name and the USER_REMOVED_MINI_APP broadcast name can be found under Tooleap.Consts.

 

Normally, the side-screen only opens when the user taps on the floating bubble.

There are times when you want to display the side-screen, even if the user hasn’t tapped on the bubble. For this, you can use the showMiniApp method:

 

If your mini-app needs to show a dialog, you should call makeDialogTooleapCompatible() right after the dialog gets shown, in order to display the dialog on-top of the side-screen.

makeDialogTooleapCompatible() is a method available inside your Tooleap extended activity.

For example:

If you’re using a DialogFragment, you should override the onStart() method of the fragment, extract the dialog from the owning activity and call makeDialogTooleapCompatible(). For example:

 

Note: Contextuality is not supported as of Android 5.0 (Lollipop) and above. This issue is scheduled to be fixed in future release. Currently, refrain from using Contextuality if the device API level is 21 or higher.

Contextuality allows you to state on top of which applications the mini-app’s bubble should appear.

For example, you can state that your mini app should appear only while the user is in your own application, or only while the user is using the browser application.

First, you need to add the following manifest permission:

Then add the following service declaration to the manifest:

 

The SDK provides two helper classes, to achieve contextuality :

A mini app can have only one type of filter list.

To set a filter list on a mini app use:

Note: Only Persistent mini apps may have a filter list. Tooleap SDK also provides several predefined filter lists:

  • CONTEXTUAL_BROWSER – An application list of all browser apps on the device
  • CONTEXTUAL_HOME_SCREEN – The device home screen application
  • CONTEXTUAL_MY_APPLICATION – The developer’s application (your app’s package name)

For example, to set a mini app that only appear on top of the browser application use:

If you are using ProGuard, you should add the following lines to your ProGuard configuration file to exclude Tooleap from being obfuscated:

 

Tooleap Guidelines