Overview

This document describes how to integrate Optimise AppButton in your Android Application. The following details how to integrate the SDK, add a placement and display a button in your app.

Prerequisites

  1. You must have an understanding of developing Android Apps
  2. You must be familiar with Android Studio as a development environment

Adding the SDK to your App

1. Go to project structure

Go to the project structure and click “+” button then click OK to add AppButton.aar file in your application as shown below.

android-appbutton-sdk1

2. Select .JAR/.AAR package

Select import .JAR/.AAR package from the options and click on Next as shown below.

android-appbutton-sdk2

3. Select AppButton.aar file

Select the AppButton.aar file from the path of your system and click on finish as shown below.

android-appbutton-sdk3

If you are using Gradle you can skip steps 4 & 5 and add the following code snippet to your App’s build.gradle file:

dependencies { 
testCompile 'junit:junit:4.12'

//Add this to dependencies section of your project
compile project(':appbutton')
}

4. Select Module Dependency

Go to project structure and under dependencies section Click on the “+” button at right corner and select Module dependency as shown below.

android-appbutton-sdk4

5. Select AppButton from the list

Select AppButton_version from the list of modules and click ok as shown below.

android-appbutton-sdk5

Initialise the SDK

1. Configure APP_ID

Configure your APP_ID in your AndroidManifest.XML file under application tag as shown below

<meta-data android:name="AppButton.APP_ID" android:value="Your APP_ID"/>

2. Add Proguard Rules

If you are using proguard-rules.pro in your app i.e. minifyEnabled true in your build.gradle file, then you must add the following code snippet to it:

-keep class com.optimise.appbutton** { *; }
-dontwarn com.optimise.appbutton.**
-keepclassmembers class * implements android.os.Parcelable {
    static ** CREATOR;
}

You can find the progurad-rules.pro in your Application’s structure e.g. yourapp/proguard-rules.pro.

3. Add ButtonPlacement to your xml layout

To show AppButtons in your UI, you must add a “ButtonPlacement” in your XML Layout. You can show multiple Buttons horizontally and vertically. Add the following code in your Layout where you want AppButton to be displayed:

<com.optimise.appbutton.button.ButtonPlacement
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:orientation="vertical"
android:id="@+id/button_placement"/>

Note: If you want to add multiple Placements then you must add multiple ButtonPlacements in your Layout.

4. Import AppButton dependencies

Add the following:

import com.optimise.appbutton.button.AppButton;
import com.optimise.appbutton.button.ButtonPlacement;
import com.optimise.appbutton.model.Placement;

5. Add A ButtonPlacement in your Java file

To add the placement in your java code you must initialize the AppButton as shown below

//Initialize app button

ButtonPlacement buttonPlacement = (ButtonPlacement) findViewById(R.id.button_placement);
AppButton appButton = AppButton.getInstance();
Placement placement = new Placement.Builder()
.addUserLocation(28.41868,77.038411)                    
.addItemLocation(28.5562, 77.1000)
.addTimeZone(“Local time”)
.addPlacementId(1).addUid("user identifier")
.addButtonPlacement(buttonPlacement) 
.build();
List<Placement> placementList = new ArrayList<>();
placementList.add(placement);
appButton.initSDK(this, placementList);

AppButton

This is the main entry point of the SDK. You must get the instance of the AppButton in order set “Your App Id” and call its init() method.

initSDK(this,placementList): Pass your Activity reference in the first parameter e.g. MainActivity.this, and List<Placement> object in the second parameter.

ButtonPlacement

This is the Class where your Buttons will be placed. The default width for this should be set as match_parent and height as wrap_content to ensure they fill their containing object.

Placement

Placement is a class where you can set your all contextual data like UserLocation, ItemLocation and ItemProperties. It has following methods:

Method Parameter Description
addUserLocation(double, double) Latitude, Longitude Pass user’s current location in this method the parameters here are latitude, longitude.
addItemLocation(double, double) Latitude, Longitude Pass the item’s location to this method the parameters here are latitude, longitude e.g. for OLA button you must pass the destination Lat, Long values to this method.
addItemProperty(String) Item This method is used to add buttons like ecommerce e.g. Flipkart. Pass a string keyword as a parameter to create this type of button.
addTimeZone(String) Time Zone Pass the local time zone of the user.
addPlacementId(int) PlacementID Pass your PlacementID provided by optimise to you in this method.
addUid(String) Unique Identifier This is an optional method. Pass a unique identifier here. You can set maximum of 5 UID’s per placement.
addButtonPlacement(ButtonPlacement) ButtonPlacement Pass the ButtonPlacement reference to this method.

If you want to add an ecommerce AppButton, e.g. Flipkart, in your App then you should initialize the SDK as follows:

ButtonPlacement buttonPlacement = (ButtonPlacement) findViewById(R.id.button_placement);
Placement placement1 = new Placement.Builder()
.addItemProperty("Samsung Mobile")
.addPlacementId(8)
.addTimeZone(“Local time”)
.addButtonPlacement(buttonPlacement)
.build();

If your app supports multiple languages you can set this in setUserLanguage method as shown below
AppButton.getInstance().setUserLanguage("en-GB");

You should set ISO 639-1 code for usetLanguage, by default the value is "en-GB".

Handling Orientation Changes

If your application supports both portrait and landscape mode, than you must add following code snippet in your AndroidManifest.XML file’s activity tag in which you are adding buttons.

android:configChanges="orientation|screenSize"

For example

<activity android:name=".YourActivity"
    android:configChanges="orientation|screenSize"/>

Styling the ButtonPlacement

You can also style the ButtonPlacement according to your theme. This is as simple as you style your widgets in layouts.

Attribute Default Value Purpose
ButtonPlacement:buttonBackgroundColor Color.WHITE Set background color of button in a placement.
ButtonPlacement:buttonBackgroundDrawable System Default Set a drawable resource file to button background. You can set any custom shape/selector in this.
ButtonPlacement:buttonTextColor Color.DKGRAY Set the text color of button in a placement.
ButtonPlacement:buttonIconVisibility visible Set the visibility of the button icon. You can set this as visible, gone, invisible.
ButtonPlacement:buttonTextSize 14sp Set the textSize of button.
ButtonPlacement:buttonTextFont System Default Set the custom font to button text.  For example you can set the font name in your strings.xml file as:-
<string name=”customFont”>Intelligent Design – Zona Pro.otf</string>
Refer this customFont to buttonTextFont property.
ButtonPlacement:buttonIconWidth 32dp Set the icon width for button.
ButtonPlacement:buttonIconHeight 32dp Set the icon height for button.
ButtonPlacement:buttonWidth match_parent Set the width for button.
ButtonPlacement:buttonHeight 45dp Set the height for button.

 

E.g.

<com.optimise.appbutton.button.ButtonPlacement
xmlns:ButtonPlacement="http://schemas.android.com/apk/res-auto"
android:layout_width="match_parent" android:layout_height="wrap_content" 
android:orientation="vertical" 
android:id="@+id/button_id" 
android:background="Your background color" 
android:padding="Padding value" 
android:layout_margin="The margin you want to provide"
ButtonPlacement:buttonTextColor="#ff0000"
ButtonPlacement:buttonIconVisibility="visible"
ButtonPlacement:buttonBackgroundColor="@android:color/white"
ButtonPlacement:buttonTextFont="@string/customFont
ButtonPlacement:buttonTextSize="14sp"/>

Note: The value set in the attributes will be set to placement, it means if there are more than one button in it, it will reflect to all the buttons.