search

mopinion / mopinion-sdk-android-web

Mopinion Mobile web SDK for Android
2 stars 1 forks source link

readme

Mopinion Mobile SDK for android (deprecated)

This SDK is deprecated! Please use our latest Android Web SDK, find it here. Looking for our SDK with native interface components? Find our latest full SDK built in native Kotlin here!

The Mopinion Mobile SDK can be used to collect feedback from Android apps based on events. To use Mopinion mobile feedback forms in your app you can include the SDK as a Library in your Android Studio project.

There are also other Mopinion SDK's available:

Contents

Release notes for version 0.3.1

Changes in 0.3.1


Installation

Install the Mopinion Mobile SDK Library by adding it to the build.gradle file of your project, as per instructions in section Android Studio - Configure your app's build config. The minimal required Android API level is 19.

Download our Mopinion Forms app from the Google Play Store to preview what your mobile forms will look like in your app.

dependencies

Our instructions already include the installation for the above external dependency, no additional steps needed.

Android Studio

Configure your app's build config

Use GitHub packages instead of Jitpack. See our addendum and then return to this README at "Main module build.gradle".

Note: Jitpack no longer works for new builds. The instructions for Jitpack were: In the main project build.gradle file add the following:

buildscript {
    repositories {
        google()
        mavenCentral()
        ...
    }
    ...
}
...
allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}
Main module build.gradle

In the build.gradle file of your main module, add the Mopinion SDK Library:

android {
    ...
}
...
dependencies {
    ...
    implementation 'com.android.volley:volley:1.2.1'
    implementation 'com.mopinion:mopinion-sdk-web:0.3.1'
}


AndroidManifest.xml

The SDK needs to connect to the Mopinion servers so the internet permission should be added to your AndroidManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.app">

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

        <application
        ...


implement the SDK

In the activity source file, include these lines to import, open and call the MopinionSDK:

import com.mopinion.mopinionsdkweb.*;
...
// idealy only init this once, i.e. in an onCreate()
Mopinion M = new Mopinion(Context context, String key, boolean log);
...
// somewhere else in the same class
M.event(String event);

example:

import com.mopinion.mopinionsdkweb.*;
...
Mopinion M = new Mopinion(this, "12345abcde");
M.event("_button");

Note that the event call is asynchronous.


extra data

From version 0.1.4 it's also possible to send extra data from the app to your form. To do this, supply a key and a value to the data() method. Add the data before calling the event() method if you want to include the data in the form that comes up for that event.

M.data(String key, String value);

Example:

import com.mopinion.mopinionsdkweb.*;
...
Mopinion M = new Mopinion(this, "12345abcde");
...
M.data("first name", "Andy");
M.data("last name", "Rubin");
...
M.event("_button");

clear extra data

From version 0.1.6 it's possible to remove all or a single key-value pair from the extra data previously supplied with the data(key,value) method. To remove a single key-value pair use this method:

M.removeData(String key)

Example:

M.removeData("first name")

To remove all supplied extra data use this method without arguments:

M.removeData()

Example:

M.removeData()


Evaluate if a form will open

The event() method of the SDK autonomously checks deployment conditions and opens a form, or not.

From SDK version 0.2.2 you can use the evaluate() and related methods to give your app more control on opening a form for proactive events or take actions when no form would have opened.

It can also be used on passive events, but such forms will always be allowed to open.

Procedure overview

  1. Call the evaluate() method and pass it a callback function that implements the Mopinion.MopinionOnEvaluateListener interface.
  2. In your callback function, check the response parameters and retrieve the formKey if there is any.
  3. Optionally, pass the formKey to the method openFormAlways() to open your form directly, ignoring any conditions in the deployment.

evaluate() method

Evaluates whether or not a form would have opened for the specified event. If without errors, the callback handler will receive the onMopinionEvaluate call with the response.

void evaluate(String event, MopinionOnEvaluateListener callbackHandler)

Parameters:

onMopinionEvaluate() method

Method where the app receives the response of the evaluate call. Defined by the Mopinion.MopinionOnEvaluateListener interface. Note that in case of any system errors this may not be called at all.

void onMopinionEvaluate(boolean hasResult, String event, @Nullable String formKey, @Nullable JSONObject response)

Parameters:

openFormAlways() method

Opens the form specified by the formkey, regardless of any proactive conditions set in the deployment.

void openFormAlways(String formKey)

Parameters:

Example of using evaluate()

This snippet of pseudo code highlights the key points on how the aforementioned procedure fits together to implement the Mopinion.MopinionOnEvaluateListener interface.

...
import com.mopinion.mopinionsdkweb.Mopinion;
...
public class MainActivity extends AppCompatActivity
                            implements Mopinion.MopinionOnEvaluateListener {
...
    Mopinion M=null;
...
    public void doSomething() {                        
        Mopinion M = new Mopinion(this, yourdeploymentkey);
        M.evaluate(event, this);    // check if a form would open
        // the actual result will be in the onMopinionEvaluate call
    }
...
    // callback handler
    @Override
    public void onMopinionEvaluate(boolean hasResult, String event, @Nullable String formKey, @Nullable JSONObject response) {
        if(hasResult) {
            // at least one form was found and all optional parameters are non-null
            M.openFormAlways(formKey); // because conditions can change every time, use the form key to open it directly
        }else{
            if(formKey !=null) {
                // Found form wouldn't open for event                
                M.openFormAlways(formKey); // we'll open it anyway using the formKey
            }else{
                // no form found for event
                ...
            }
        }
    }
...

It's also possible to integrate the callback handler directly in the evaluate() call, then you don't need to implement the interface at your class level. The evaluate call would then look like this:

...
    M.evaluate(event, new Mopinion.MopinionOnEvaluateListener() {
            @Override
            public void onMopinionEvaluate(boolean hasResult, String event, @Nullable String formKey, @Nullable JSONObject response) {
                // here the code to check the parameters like hasResult, formKey, etc
                ...
            }
        });


Using callback mode

By default the SDK manages the feedback form autonomously without further involving your app. Version 0.3.0 introduces asynchronous callbacks to inform your code of certain actions (MopinionEvent).

Provide a callback handler to receive a response, containing either data or possible error information.

Procedure overview

  1. Call the event() method and pass it a callback function that implements the MopinionEventListener.onMopinionEvent interface.
  2. In your callback function onMopinionEvent(), check the kind of mopinionEvent and optionally call didSucceed() or hasErrors() on the response to check for errors.
  3. Optionally, call hasData() on the response object to check if there is data.
  4. Depending on the kind of mopinionEvent, check for the presence of data specified by a ResponseDataKey using the call hasData(ResponseDataKey) on the response.
  5. To get the data, call getString(ResponseDataKey) respectively getJSONObject(ResponseDataKey) on the response, depending on the type of data to retrieve.

You can also provide an optional error-callback handler to event() to seperately receive responses with error information. In that case the primary handler only receives responses without errors.


Callback variants of the event() method

Triggers an event you defined in your deployment to open a form and receive MopinionEvent callbacks. If you don't specify a failHandler, the callback handler will also receive error responses.

void event(String event, MopinionEventListener callbackHandler)
void event(String event, MopinionEventListener callbackHandler, MopinionEventErrorListener failHandler)

Parameters:


Callback methods onMopinionEvent() and onMopinionEventError()

These methods you implement in your code to receive MopinionEvents. They have the same parameters to pass you a response with optional additional information. What information is provided depends on the type of MopinionEvent and its origin.

void onMopinionEvent(MopinionEvent mopinionEvent, MopinionResponse response)
void onMopinionEventError(MopinionEvent mopinionEvent, MopinionResponse response)

Parameters:


MopinionResponse object

The data collection present in this object depends on the kind of MopinionEvent and its origin. The data is a key-value collection. Both data and errors can be missing. The response object contains methods to inspect and retrieve them.

Getting data with response.get() and response.hasData()

Check with hasData(key) first, as the get<>(key) methods can return null. Pass a standard ResponseDataKey to these methods for the data you're interested in.

ResponseDataKey Method to read it Description
DATA_JSONOBJECT .getJSONObject() 'raw' JSONObject with all available data
FORM_KEY .getString() the internal unique identifier for the form
FORM_NAME .getString() the name of the form. Distinct from the title of the form.


MopinionEvents and provided data in response

This is the data that can be present for a certain MopinionEvent:

MopinionEvent ResponseDataKeys Remarks
FORM_OPEN DATA_JSONOBJECT
  FORM_KEY
  FORM_NAME
FORM_SENT DATA_JSONOBJECT
  FORM_KEY
  FORM_NAME
FORM_CLOSED DATA_JSONOBJECT Currently only automatically closed forms provide data
  FORM_KEY only when autoclosed
  FORM_NAME only when autoclosed

The order in which MopinionEvents occur is:

1. FORM_OPEN
2. FORM_SENT (only if the user submits a form)
3. FORM_CLOSED


Reading response errors

Call response.hasErrors() on, followed by response.getErrorString() to get the error as text. The getErrorString() method might return null.


Callback handler example

Pseudo code to show the usage of the event() callback using the involved objects.

...
Mopinion M = new Mopinion(this, yourdeploymentkey);
...
// open the form and wait for the events to appear
M.event(event, new MopinionEventListener() {
    @Override
    public void onMopinionEvent(MopinionEvent mopinionEvent, MopinionResponse response) {
        switch(mopinionEvent) {
            case FORM_OPEN:
                // specifies a default string if form key is null
                Log.d("CallbackDemo","a form opened, form key = " + response.getString(ResponseDataKey.FORM_KEY, "unspecified"));
                break;
            case FORM_SENT:
                try {
                    JSONObject jsonData = response.getJSONObject(ResponseDataKey.DATA_JSONOBJECT);
                    Log.d("CallbackDemo","User submitted the form, raw data object=" + jsonData.toString());
                } catch (JSONException e) {
                    // something wrong with the json data
                    e.printStackTrace();
                }
                break;
            case FORM_CLOSED:
                if(response.hasData(ResponseDataKey.FORM_NAME)) {
                    Log.d("CallbackDemo", "The form '" + response.getString(ResponseDataKey.FORM_NAME) + "' closed");
                } else {
                    Log.d("CallbackDemo", "The form closed, no name was given.");
                }
                break;
            default:
                 Log.d("CallbackDemo","Ignoring this event.");
        }
    }
}, 
// dedicated error handler
new MopinionEventErrorListener() {
    @Override
    public void onMopinionEventError(MopinionEvent mopinionEvent, MopinionResponse response) {
        if( response.hasErrors() ) {
            Log.d("CallbackDemo","Event " + mopinionEvent.name() + " encountered an error:" + response.getErrorString());
        }
    }
);


Edit triggers

In the Mopinion deployment editor you can define event names and triggers that will work with the SDK event names that you used in your app. Login to your Mopinion account and go to Data collection, Deployments to use this functionality.

Deployment Editor

The custom defined events can be used in combination with rules/conditions: