API Guide
Create a Mini App
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”:
|
1 2 3 4 |
public class MyTooleapActivity extends TooleapActivities.Activity { // Your activity code... } |
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 (onCreate, onResume, onPause 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:
|
1 2 3 4 5 6 7 8 |
<activity android:name=".MyTooleapActivity" android:theme="@android:style/Theme.Translucent" android:launchMode="singleInstance" android:taskAffinity=".tooleap"> <intent-filter> <action android:name="com.tooleap.sdk.TOOLEAP_SHOW"/> </intent-filter> </activity> |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<activity android:name=".MyTooleapActivity" android:theme="@android:style/Theme.Translucent" android:launchMode="singleInstance" android:taskAffinity=".tooleap"> <meta-data android:name="com.tooleap.sdk.theme" android:resource="Your.Theme"/> <intent-filter> <action android:name="com.tooleap.sdk.TOOLEAP_SHOW"/> </intent-filter> </activity> <!-- For example: --> <meta-data android:name="com.tooleap.sdk.theme" android:resource="@style/Theme.Sherlock.Light.DarkActionBar"/> <meta-data android:name="com.tooleap.sdk.theme" android:resource="@android:style/Theme.Holo.Light""/> |
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 –
|
1 2 3 4 5 6 7 8 9 |
<activity android:name=".MyTooleapActivity" android:theme="@android:style/Theme.Translucent" android:launchMode="singleInstance" android:screenOrientation="user" android:taskAffinity=".tooleap"> <intent-filter> <action android:name="com.tooleap.sdk.TOOLEAP_SHOW"/> </intent-filter> </activity> |
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).
|
1 2 3 4 |
public class MyActivity extends TooleapActivities.Activity { // Your activity code... } |
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:
|
1 2 3 4 |
public class MyTooleapActivity extends MyActivity { // No need for code here. MyTooleapActivity will inherit all methods and logic from MyActivity class } |
Finally, add your new activity to the manifest, as already described before:
|
1 2 3 4 5 6 7 8 |
<activity android:name=".MyTooleapActivity" android:theme="@android:style/Theme.Translucent" android:launchMode="singleInstance" android:taskAffinity=".tooleap"> <intent-filter> <action android:name="com.tooleap.sdk.TOOLEAP_SHOW"/> </intent-filter> </activity> |
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.
Display a mini app
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:
|
1 |
Intent intent = new Intent(context, MyTooleapActivity.class); |
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.
|
1 2 3 4 5 6 |
TooleapPopOutMiniApp miniApp = new TooleapPopOutMiniApp(context, intent); // An example for some customizations of a mini app. You can use your own... miniApp.contentTitle = "My First Mini App"; miniApp.notificationText = "Hello! I'm the Tooleap bubble"; miniApp.bubbleBackgroundColor = 0x78FFFFFF; |
Now you can display the mini app using the addMiniApp method:
|
1 2 |
Tooleap tooleap = Tooleap.getInstance(context); tooleap.addMiniApp(miniApp); |
Customize Your Mini App
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:
|
1 2 |
TooleapPopOutMiniApp miniApp = new TooleapPopOutMiniApp(context, intent); miniApp.contentTitle = "My mini app title"; |
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.
Figure 1. The Bubble that includes the [1] app icon, [2] bubble background, [3] notification badge and [4] the notification text balloon.
Figure 2. The title bar that includes the [1] app icon, [5] content title and [6] the dismiss button.
Figure 3. The bottom bar that includes the [1] app icon and the [3] notification badge.
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) |
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 | The Bubble’s background color is in ARGB format (e.g 0x99AAFFCC) | |
|
3 |
Notification Badge Number | 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 | ||
|
5 |
Content Title | ||
|
6 |
Dismiss button |
TooleapPersistentMiniApp.allowUserToDismiss(boolean isDismissible) |
Can only be customized in Persistent or Home mini apps. See Mini App Types guide |
|
7 |
Content Text | ||
|
8 |
When the mini app was added |
Manage your mini apps
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:
|
1 2 |
Tooleap tooleap = Tooleap.getInstance(context); long miniAppId = tooleap.addMiniApp(miniApp); // Keep the mini app id to modify the mini app later |
The SDK enables you to manage your existing mini apps using the following methods:
Get:
Update:
updateMiniApp(long appId, TooleapMiniApp miniApp)updateMiniAppAndNotify(long appId, TooleapMiniApp miniApp)
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:
|
1 2 3 4 5 6 7 |
Tooleap tooleap = Tooleap.getInstance(context); TooleapPopOutMiniApp miniApp = tooleap.getMiniApp(appId); miniApp.notificationText = "Look! A text balloon beyond my wildest dreams!!"; miniApp.notificationBadgeNumber = 1; tooleap.updateMiniAppAndNotify(appId, miniApp); |
Mini App Types
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.
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:
|
1 |
TooleapNotificationMiniApp miniApp = new TooleapNotificationMiniApp(context, MyTooleapActivity.class); |
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:
|
1 |
TooleapPopOutMiniApp miniApp = new TooleapPopOutMiniApp(context, MyTooleapActivity.class); |
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 inTooleapPersistentMiniAppclass. - 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:
|
1 |
TooleapPersistentMiniApp miniApp = new TooleapPersistentMiniApp(context, MyTooleapActivity.class); |
Add to your AndroidManifest.xml file the following permission:
|
1 |
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" /> |
Add to your AndroidManifest.xml file the BOOT_COMPLETED intent action under the TooleapReceiver tag, so it should look like this:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<receiver android:name="com.tooleap.sdk.TooleapReceiver"> <intent-filter> <action android:name="android.intent.action.BOOT_COMPLETED"/> </intent-filter> <intent-filter> <action android:name="android.intent.action.PACKAGE_REPLACED"/> <data android:scheme="package"/> </intent-filter> <intent-filter> <action android:name="com.tooleap.sdk.TOOLEAP_ACTION"/> </intent-filter> </receiver> |
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 inTooleapHomeMiniAppclass. - 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:
|
1 |
TooleapHomeMiniApp miniApp = new TooleapHomeMiniApp(context, MyTooleapActivity.class); |
Add to your AndroidManifest.xml file the following permission:
|
1 2 |
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" /> <uses-permission android:name="android.permission.GET_TASKS" /> |
Add to your AndroidManifest.xml file the BOOT_COMPLETED intent action under the TooleapReceiver tag, so it should look like this:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
<receiver android:name="com.tooleap.sdk.TooleapReceiver"> <intent-filter> <action android:name="android.intent.action.BOOT_COMPLETED"/> </intent-filter> <intent-filter> <action android:name="android.intent.action.PACKAGE_REPLACED"/> <data android:scheme="package"/> </intent-filter> <intent-filter> <action android:name="com.tooleap.sdk.TOOLEAP_ACTION"/> </intent-filter> </receiver> |
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 |
Tooleap Activities
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:
|
1 2 3 4 |
public class MyTooleapActivity extends TooleapActivities.FragmentActivity { // Your activity code... } |
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:
|
1 2 |
<activity android:name="com.tooleap.sdk.TooleapProxyActivity" android:taskAffinity=".tooleapProxy" /> |
Notification Helper
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:
|
1 2 3 4 5 6 |
Tooleap tooleap = Tooleap.getInstance(context); tooleap.buildNotification(miniAppId) .setNotificationText("Look! This is a notification!") .incrementBadge() .buildAndNotify(); |
Note: Using the notification helper is the same as calling updateMiniAppAndNotify.
Events
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:
|
1 2 3 4 5 6 7 |
BroadcastReceiver myBroadcastReceiver = new BroadcastReceiver() { @Overide public void onReceive(Context context, Intent intent) { long miniAppId = intent.getLongExtra(Tooleap.Consts.APP_ID, 0); // Get the removed mini app id // Do something... } }; |
Note that both the APP_ID parameter name and the USER_REMOVED_MINI_APP broadcast name can be found under Tooleap.Consts.
Display the Side Screen Programmatically
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:
|
1 2 3 4 5 6 7 8 9 |
// Declare your mini app ... Tooleap tooleap = Tooleap.getInstance(context); // Add the mini app long appId = tooleap.addMiniApp(miniApp); // open the side screen tooleap.showMiniApp(appId); |
Handling Dialogs
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:
|
1 2 3 4 |
final ProgressDialog dialog = new ProgressDialog(this); dialog.setMessage(getString(R.string.dialog_loading_updates)); dialog.show(); makeDialogTooleapCompatible(dialog); |
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
public class MyAlertDialogFragment extends DialogFragment { public static MyAlertDialogFragment newInstance(int title) { MyAlertDialogFragment frag = new MyAlertDialogFragment(); Bundle args = new Bundle(); return frag; } @Override public Dialog onCreateDialog(Bundle savedInstanceState) { return new AlertDialog.Builder(getActivity()) .setTitle("My Title") .create(); } @Override public void onStart() { super.onStart(); ((TooleapActivities.Activity)getActivity()).makeDialogTooleapCompatible(getDialog()); } } |
Contextuality
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:
|
1 |
<uses-permission android:name="android.permission.GET_TASKS" /> |
Then add the following service declaration to the manifest:
|
1 2 |
<service android:name="com.tooleap.sdk.TooleapContextService" android:process=":ContextService"/> |
The SDK provides two helper classes, to achieve contextuality :
TooleapApplicationFilterList.WhiteList– A list of application package names where the bubble will appear on top of.TooleapApplicationFilterList.BlackList– A list of application package names where the bubble will not appear on top of.
A mini app can have only one type of filter list.
To set a filter list on a mini app use:
|
1 2 3 4 5 6 |
TooleapPersistentMiniApp miniApp = new TooleapPersistentMiniApp(context, intent); TooleapApplicationFilterList.WhiteList whiteList = new TooleapApplicationFilterList.WhiteList(); whiteList.addFilter(/* REPLACE THIS WITH THE DESIRED PACKAGE NAME: */ "application.package.name"); miniApp.setFilterList(whiteList); tooleap.addMiniApp(miniApp); |
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:
|
1 2 3 4 5 6 |
TooleapPersistentMiniApp miniApp = new TooleapPersistentMiniApp(context, intent); TooleapApplicationFilterList.WhiteList whiteList = new TooleapApplicationFilterList.WhiteList(); whiteList.addFilter(TooleapApplicationFilterList.CONTEXTUAL_BROWSER); miniApp.setFilterList(whiteList); tooleap.addMiniApp(miniApp); |
Proguard Support
If you are using ProGuard, you should add the following lines to your ProGuard configuration file to exclude Tooleap from being obfuscated:
|
1 2 3 |
-keep class com.tooleap.** { *; } -dontwarn com.tooleap.** -dontnote com.tooleap.** |
