BLiP Chat for Android
SDK to easily add BLiP Chat's widget to your Android app. For more information, see BLiP portal and BLiP documentation. See supported versions here.
Installation
Add the jcenter maven repository reference to build.gradle file of your project
allprojects {
repositories {
//others repository dependencies
jcenter()
}
}
Grab jar via Gradle:
implementation 'net.take:blip-chat:2.1.24'
or Maven:
<dependency>
<groupId>net.take</groupId>
<artifactId>blip-chat</artifactId>
<version>2.1.24</version>
<type>pom</type>
</dependency>
or download the latest JAR and import into your app.
Snapshots of the development version are available at Sonatype's snapshots
repository.
How to use
Quick start
Prerequisites
- Add the INTERNET permissions to AndroidManifest.xml in order to use this library. If there is a request location on your chatbot flow, you should also add the ACCESS_FINE_LOCATION permission. To send or download files on BLiP Chat, add WRITE_EXTERNAL_STORAGE, READ_EXTERNAL_STORAGE and CAMERA permissions.
<manifest xlmns:android...>
...
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.CAMERA" />
<application ...
</manifest>
It is also necessary to add gson dependency to your app once BLiP Chat uses this library.
implementation 'com.google.code.gson:gson:2.8.5'
Setting your SDK
After including the SDK reference in your project, you need to get your app key on BLiP portal. Choose the desired bot, go to the upper menu and access Channels > Blip Chat
. On the Setup
tab you will be able to get the required app key. You will also need to sign up your Android Application Id on the Domains
section in order to enable your chatbot in your app.
Opening the BLiP conversation widget
Opening a new thread is a very simple process. Use BlipClient helper class and call openBlipThread method
BlipClient.openBlipThread(context, "YOUR_APP_KEY");
For instance, imagine that when your MainActivity is loaded you want to establish a new conversation between customer and chatbot.
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
BlipClient.openBlipThread(context, "YOUR_APP_KEY");
}
}
Advanced features
Defining authentication type
BLiP Chat's Android SDK supports two user authentication types. It is possible to define which authentication method will be used to identify your client.
- Not integrated - Users will receive a guest account to interact with the chatbot.
- Integrated - Users will receive an account identified by developer to interact with the chatbot. User data must be provided passing a BlipOptions instance as parameter on BlipClient.openThread method. You can set 2 properties:
authConfig
andaccount
.
*Auth Config
Property | Description |
---|---|
authType | Defines the auth type to be used |
userIdentity | The user identifier |
userPassword | The user password |
*Required if on integrated auth type.
To define the user authetication type, use the AuthType enum on authType property of BlipOptions. Possible values for authType are: AuthType.GUEST
(Not integrated) and AuthType.DEV
(Integrated).
Note: AuthType.GUEST
will be used if 'authType' is not defined.
*Account
Check this link to see possible properties.
Example
import net.take.blipchat.AuthType;
import net.take.blipchat.BlipClient;
import net.take.blipchat.models.AuthConfig;
import net.take.blipchat.models.BlipOptions;
...
AuthConfig authConfig = new AuthConfig(AuthType.Dev, "userId123PS","pass123PS");
Account account = new Account();
account.setFullName("User Name Android123");
account.setEmail("[email protected]");
BlipOptions blipOptions = new BlipOptions();
blipOptions.setAuthConfig(authConfig);
blipOptions.setAccount(account);
BlipClient.openBlipThread(context, APP_KEY, blipOptions);
Using Organization
To use organization in BLiP Chat's Android SDK, you must assign options to your organization's BLiP Chat URL.
Example
import net.take.blipchat.AuthType;
import net.take.blipchat.BlipClient;
import net.take.blipchat.models.AuthConfig;
import net.take.blipchat.models.BlipOptions;
...
AuthConfig authConfig = new AuthConfig(AuthType.Dev, "userId123PS","pass123PS");
Account account = new Account();
account.setFullName("User Name Android123");
account.setEmail("[email protected]");
BlipOptions blipOptions = new BlipOptions();
blipOptions.setAuthConfig(authConfig);
blipOptions.setAccount(account);
blipOptions.setCustomCommonUrl("https://take.chat.blip.ai/"); // Use the organization chat url
BlipClient.openBlipThread(context, APP_KEY, blipOptions);
ProGuard
Android apps that use ProGuard to obfuscate code need to add an exception in file proguard-rules.pro
to not obfuscate the BLiP Chat code, otherwise, some BLiP Chat classes may not work properly which makes it impossible to open the chat.
Example
-keepattributes JavascriptInterface
-keepclassmembers class * {
@android.webkit.JavascriptInterface <methods>;
}
-keepclassmembers class net.take.blipchat.webview.WebAppInterface {
public *;
}
-dontwarn org.w3c.dom.bootstrap.DOMImplementationRegistry
-keepclassmembers class net.take.blipchat.models.** {
static final long serialVersionUID;
private static final java.io.ObjectStreamField[] serialPersistentFields;
!static !transient <fields>;
private void writeObject(java.io.ObjectOutputStream);
private void readObject(java.io.ObjectInputStream);
java.lang.Object writeReplace();
java.lang.Object readResolve();
}
-keep class com.firebase.** { *; }
-keep class org.apache.** { *; }
-keepnames class com.fasterxml.jackson.** { *; }
-keepnames class javax.servlet.** { *; }
-keepnames class org.ietf.jgss.** { *; }
-dontwarn org.apache.**
-dontwarn org.w3c.dom.**
-dontwarn retrofit2.**
-keep class com.google.android.gms.internal.** { *; }
Optional properties
Property | Description |
---|---|
Account | Set the bot's user information |
HideMenu | Show/hide chat menu |
Example
AuthConfig authConfig = new AuthConfig(AuthType.Dev, "[email protected]","123456");
Map<String, String> extras = new HashMap<>();
String fcmUserToken = FirebaseInstanceId.getInstance().getToken();
extras.put("#inbox.forwardTo", String.format("%[email protected]", fcmUserToken));
Account account = new Account();
account.setFullName("luizpush");
account.setEmail("[email protected]");
account.setEncryptMessageContent(true);
account.setExtras(extras);
BlipOptions blipOptions = new BlipOptions();
blipOptions.setAuthConfig(authConfig);
blipOptions.setAccount(account);
blipOptions.setHideMenu(true);
BlipClient.openBlipThread(SandboxAppActivity.this, BuildConfig.APPKEY, blipOptions);
Support
Android 4.4 (Kitkat)* or later
*BLiP Chat for Android does not support file input on Android 4.4.
License
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.