proxi.cloud : Integrate SDK 3.x

Below is a list of steps neccessary to hook-up your Android app with the proxi.cloud panel.

Remember to set-up your application in the panel before integrating the SDK into your app. Go to https://panel.proxi.cloud and generate an API key for your app.

First, you need to add SDK dependency to your app’s gradle file sdk. There are two supported releases, they differ by supported play-services-location library version. The last number represents supported version (up to 20 or 21+). play services location 21.0.0 introduced some breaking changes play services release notes.

  dependencies {
      implementation 'cloud.proxi.sdk:cloud.proxi.sdk:3.0.1.21'
  }

  dependencies {
      implementation 'cloud.proxi.sdk:cloud.proxi.sdk:3.0.1.20'
  }

Add the following repositories to your project’s build.gradle file:

allprojects {
    repositories {
        mavenCentral()
        maven { url "https://jitpack.io" }
    }
}

Manifest Permissions

ACCESS_FINE_LOCATION is required in your manifest for the majority of functions to work.

ACCESS_BACKGROUND_LOCATION is required if your app targets Android 10 (API 29) for geofencing and other functions to work in background.

Important!

Starting from 29 March 2021 Google Play Store requires apps with ACCESS_BACKGROUND_LOCATION permission to fill aditional permission declaration form. You can read more about it on this page

ACCESS_WIFI_STATE and CHANGE_WIFI_STATE are neccessary to take advantage of the WiFi trigger

Important!

Starting from Android 6 (API level 23) the user needs to be asked explicitly for the location permission. More information on this page.

Integration

Enable the SDK in your Application’s onCreate() method.

class ExampleApp: Application() {
    override fun onCreate() {
        super.onCreate()
        ProxiCloudSdk.getInstance(this);
    }
}

add API Key to your app’s manifest file. API Key is 64 digit long hex number. Example:

    <application>
    
        <meta-data
            android:name="proxi_cloud_api_key"
            android:value="1f9e6d87b6e31e807647b36152da82fb79e3bd9614bf9bd90ca49930e287ecf7" />
    </application>

Setting up play services for Google Play Store

Make sure that you compile in a correct version of Google play services (if you are not using them already) - this is required for geofencing and other subcomponents to work

  implementation 'com.google.android.gms:play-services-location:21.0.1' //or 20.0.0 for version 3.x.x.20
  implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'

If GDPR rules are applicable to your app, the user must consent to data collection. This includes information collected by the Proxi.cloud SDK. Please consult our privacy policy for more details on this topic.

Once the user provides appropriate consent to processing of their data, simply run:

  ProxiCloudSdk.getInstance(application).setGdprConsent(true);

If for any reason the user withdraws their consent or you want to prevent SDK from collecting data including the user’s advertising identifier. Just run the same method with ‘false’ as its argument.

  ProxiCloudSdk.getInstance(application).setGdprConsent(false);

Please make sure that the Proxi.cloud privacy policy is linked in your GDPR consent information screen and Proxi.cloud is listed among your trusted partners. Feel free to contact Proxi.cloud GDPR team in case of any questions.

Notifications and actions

Notifications are handled internally by SDK. There are three types of possible actions as selected in the proximity panel. They define what happen on notification being opened and how app shoud handle the provided URL.

Notification
Website
InApp

All of these notifications can be enhanced with graphic content. Just upload image in push notification settings in the panel.

Notification

Opening notification will start launch activity.

Website

Clicking notification will open provided url in a browser.

In App

Opening notification will start activity via deep link. To make it work you need to add intent filter for url in manifest within target activity tag.

Sample filter for url: example://cloud.proxi.test

<activity
    android:name="cloud.proxi.test.ExampleApp">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="example"
              android:host="cloud.proxi.test"/>
    </intent-filter>
</activity>

More information can be found on the Android Developer page

Notification conversion

For SDK to report that notification has been opened action uuid needs to be retrieved from activity launching intent. Then, report conversion with given UUID and adequate Conversion status. Statuses other than SUCCESS are handled by the SDK internally.

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        val actionInstanceUuid: String =
            intent.getStringExtra(ProxiCloudConstants.ACTION_INSTANCE_UUID)
        if (actionInstanceUuid != null) {
            ProxiCloudSdk.getInstance(application)
                .notifyConversionStatus(actionInstanceUuid, Conversion.SUCCESS)
        }
    }

Notification customisation

If you require different look and feel of the notifications generated by the SDK, you can customize them through meta-data in your manifest. Below are shown all possible options, but you my choose to modify only some of them (or none).

<application>
    <!--set large icon for your notification, default is set to null -->
    <meta-data
        android:name="cloud.proxi.notification.large_icon"
        android:resource="@mipmap/your_large_icon" />

    <!-- set small icon, default is set to google material notification icon -->
    <meta-data
        android:name="cloud.proxi.notification.small_icon"
        android:resource="@drawable/your_small_icon" />

    <!--notification color, default is grey -->
    <meta-data
        android:name="cloud.proxi.notification.color"
        android:resource="@color/your_color" />
        
    <!--if set to true (default is false), thumbnail of image from graphic push will be shown in place of large icon for collapsed notification view--> 
    <meta-data
        android:name="cloud.proxi.notification.thumbnail_enabled"
        android:value="true" />

    <!-- Set your own notification channel. If not provided, default channel named "Geolocation Push Notifications" will be used -->
    <meta-data
        android:name="cloud.proxi.notification.channel_id"
        android:value="your_channel_id" />

</application>

Reporting custom events

Starting from v2.3.x, the SDK allows to report custom events which then can be agreggated and analysed in the proxi.cloud platform. To use this functionality simply call the ReportEvent method when the event you wish to report occurs. The SDK will automatically add current timestamp and location (if it can be established) to the event and send it back to the proxi.cloud platform for further aggregation where it can be used to create custom reports and analytics. Below is an example showing how to report particular product view within the app.

ProxiCloudSdk.getInstance(application).reportEvent("product_viewed", "{'\"brand\":\"Awesome Brand\",\"name\":\"Awesome Product\",\"product_id\":1337}");

Developer documentation for proxi.cloud SDK, API and Panel

Integrate SDK 3.x