Android integration manual 2.4.0

Example Gradle configuration:

To add the library to the project put an aar file in libs catalog and modify gradle.Build file
Parameter ‘name’ in the ‘compile’ section should be named the same as the library file without the extension.

repositories {
    flatDir {
        dirs 'libs'
    }
}
dependencies {
    compile(name:'appmanagolibrary-release', ext:'aar')
}

For other tools configuration check how to add the external library to the project in their documentation.

Library configuration

In the strings.xml file of integrated application add the following entries:

  • appmanago_launch_time
    It defines the time interval between successive uses of the module/function after which we
    assume that the application was restarted. The value is given in minutes.

    <string name="appmanago_launch_time">30</string>

    For 30 – launch event will be registered when the application has been inactive for 30 minutes and then resumed.

  • appmanago_sync_meantime
    It/ Variable/ The entry defines how often the platform should make an attempt to synchronize events, which took place when there was no Internet connection. The value is given in minutes.

    <string name="appmanago_sync_meantime">360</string>

    In the example application will try to synchronize every 360 minutes.

  • appmanago_endpoint
    It/ Variable/ The entry defines the endpoint. Default endpoint for APPmanago is

    <string name="appmanago_endpoint">https://click.appmanago.com</string>
  • appmanago_vendor_id
    Vendor identificator; itan be found after logging in to the APPmanago panel Settings -> Account.

    <string name="appmanago_vendor_id">VENDOR_ID</string>
  • appmanago_application_id
    Simple ID of the application.The ID is created when you add a new application to Create app panel.

    <string name="appmanago_application_id">APPLICATION_SIMPLE_ID</string>
  • Imal appmanago_sender_id
    GCM sender id. The ID generated after registering the app on Google website. It can be found in the configuration file. . More information – in Google Cloud Messaging paragraph.

    <string name="appmanago_sender_id">SENDER_ID</string>
  • appmanago_gps_sync_time
    Minimal interval between sending GPS coordinates (in minutes).

    <string name="appmanago_gps_sync_time">1</string>
  • appmanago_gps_front_available
    Flag determining whether the location should be updated continuously or only when the application is active (0 – still, 1 – only when the application is active).

    <string name="appmanago_gps_front_available">0</string>
  • appmanago_gps_accuracy
    Accuracy of location determination and also battery consumption:
    – HIGH – high accuracy, the device will determine the most accurate location,
    – BALANCED – (recommended) – accuracy up to 100m with the best ratio of performance to battery consumption,
    – LOW – accuracy up to 10km, low battery consumption,
    – PASSIVE – passive mode, the application is waiting for the location to be updated by other applications, it does not use energy to determine it,
    (to avoid battery drain, location system has 10s timeout – if within 10 second location is not resolved, process will be canceled)

    <string name="appmanago_gps_accuracy">HIGH</string>

Sending events to APPmanago

Communication of events is carried out by the object of AmMonitor class.

Initiation of that object can be set as in below example. It can take place in onCreate() method.

private AmMonitoring amMonitor;
amMonitor = AmMonitor.initLibrary(getApplicationContext());

objects should be created ‘per activity’ as they contain components responsible for measuring time spent in a module.

One must override methods onResume() and onPause()

    @Override
    protected void onResume() {
        super.onResume();
        amMonitor.eventStarted(ACTIVITY_NAME, new AmProperties());
    }


    @Override
    protected void onPause() {
        super.onPause();
        amMonitor.eventEnded(ACTIVITY_NAME, new AmProperties());
    }

Integration with Google Cloud Messaging (GCM)

To add GCM to an application one must execute client’s manual on Google page:
https://developers.google.com/cloud-messaging/android/client

In order to recieve Server API Key and Sender ID one should register the application. Those IDs should be in APPmanago Properties->GCM account dashboard. The google-services.json file should be added to android application as well.

The next step is adding to AndroidManifest.xml:


  <uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
  <uses-permission android:name="<YOUR_API_PACKAGE>.permission.C2D_MESSAGE" />

<permission
    android:name="<YOUR_API_PACKAGE>.permission.C2D_MESSAGE"
    android:protectionLevel="signature" />

    <receiver
        android:name="com.google.android.gms.gcm.GcmReceiver"
        android:exported="true"
        android:permission="com.google.android.c2dm.permission.SEND">
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
            <category android:name="<YOUR_PACKAGE_NAME>" />
        </intent-filter>
    </receiver>

    <service
        android:name="com.appmanago.lib.gcm.AmGcmListenerService"
        android:exported="false" >
        <intent-filter>
            <action android:name="com.google.android.c2dm.intent.RECEIVE" />
        </intent-filter>
    </service>

    <service
        android:name="com.appmanago.lib.gcm.AmInstanceIDListenerService"
        android:exported="false">
        <intent-filter>
            <action android:name="com.google.android.gms.iid.InstanceID"/>
        </intent-filter>
    </service>

    <service
        android:name="com.appmanago.lib.gcm.AmRegistrationIntentService"
        android:exported="false">
    </service>

AmRegistrationIntentService class is running automatically and it executes sending RegistrationId to the server. If you want to support it by yourself just overwrite the onHandleIntent() element in this library class.

In onCreate() method add checking Google api availability.

        if (checkPlayServices()) {
            
            startService(new Intent(this, AmRegistrationIntentService.class);
        }

Add those methods to execute in onCreate()

    private boolean checkPlayServices() {
        GoogleApiAvailability apiAvailability = GoogleApiAvailability.getInstance();
        int resultCode = apiAvailability.isGooglePlayServicesAvailable(this);
        if (resultCode != ConnectionResult.SUCCESS) {
            if (apiAvailability.isUserResolvableError(resultCode)) {
                apiAvailability.getErrorDialog(this, resultCode, 9000)
                        .show();
            } else {
                Log.i(Constants.LOG_TAG, "This device is not supported.");
                finish();
            }
            return false;
        }
        return true;
    }

Rich notification

It is able to add rich notification to push e.g. a image. In create push it is necessary to check “Rich content” checkbox and add needed attributes. It is recommended to make it custom but it is possible to use the default implementation. For default in APPmanago library when it is received push with rich notification with type “jpg” or “png” and link to picture then it will show this image below notification.

To use custom rich notification it is need to override richPushNotification() method in class PushActionExecutor To do this it is necessary to change class in AndroidManifest.xml com.appmanago.lib.gcm.AmGcmListenerService to new class that creates instead PushActionExecutor its extension with override richPushNotification() method.

Beacon

Beacons are avaiable on Android since Android Lollipop when it supports Bluetooth LE. It is need to add to AndroidManifest.xml permissions to Bluetooth:

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

In place where we start to search for beacons we need to initialize APPmanago library to support searching beacons:

amBeaconMonitor = AmBeaconMonitor.initLibrary(getApplicationContext());

Before search it is needed to check if:

– Android version is above or equals Lollipop
– Bluetooth is reached in device and it is on

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
   mBluetoothAdapter = BluetoothAdapter.getDefaultAdapter();
   if(mBluetoothAdapter != null && mBluetoothAdapter.isEnabled()) {
       mBluetoothLeScanner = mBluetoothAdapter.getBluetoothLeScanner();
       mBluetoothLeScanner.startScan(
               amBeaconMonitor.getScanFilter(BEACON_UUID),
               amBeaconMonitor.getScanSettings(), 
               amBeaconMonitor.getScanCallback());
   }
}

To stop searching Beacons:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
   mBluetoothLeScanner.stopScan(amBeaconMonitor.getScanCallback());
}

The methods used to monitor customer behavior:

amMonitor.eventStarted(ACTIVITY_NAME, amProperties);

is used during the launch of the module / (Activity). ACTIVITY_NAME is simpleID from APPmanago.
Usually the method will be called in the method onResume() where it’ll start to start count duration of the module usage.

amMonitor.eventEnded(ACTIVITY_NAME, amProperties);

is used at the end of (Activity) module execution.
Usually it will be used in the method OnPause() where it’ll stop counting the time of module usage.

amMonitor.eventCustom(CUSTOM_EVENT_NAME, amProperties);

is used during the custom events transfer. The events should be defined in APPmanago as custom events as well.

amMonitor.clicked(FUNCTION_NAME, amProperties);

is used during the launch of methods mapped in APPmanago. It will count how many times function was used. You can add details like date as amProperties.

amMonitor.syncEmail(EMAIL_ADDRESS);

is used to add user’s email address. The email will be used as user’s ID on the platform.

amMonitor.syncMsisdn(PHONE_NUMBER);

is used to add users phone number/MSISDN.

amMonitor.sendUserProperties(PROPERTIES_MAP);

It sends user properties to APPmanago. It is a key-value map where we can store data about user, e.g., name, surname, shoe number or birthdate. We can use this data to personalize push notifications, and set the dynamic segments.

amMonitor.sendLocation(WIDTH, LENGTH);

is used to send users’location.

AmExtras amExtras = amMonitor.getAmExtras(bundle)
amExtras.getPayload();
amExtras.getPushType();

It allows the application to read the type and content of payload from the notification. It is executed when user receives a push. A developer can use the data from payload to e.g., redirect to app’s module, send an event, view an image, and many more.