Integrate SDK

Implementation

The following manual describes how to implement Proxi.cloud SDK into your Android application.

If you would like to check an example app with Proxi.cloud SDK already implemented, check: Example App GIT repository

Setup repositories

Proxi.cloud SDK is distributed via maven central repository.

Check for the newest release

So it is required to add mavenCentral() to the list of repositories, jitpack repository is also needed due to one of the dependencies used by Proxi.cloud SDK.

Depending on the way your project is setup it is done either in project’s root build.gradle file in allProjects/repositories section or using dependencyResolutionManagement in project’s settings.gradle file.

Option 1: Project level build.gradle allProjects/repositories

// project_directory/build.gradle
allprojects {
    repositories {
        mavenCentral()
        maven { url "https://jitpack.io" }
        // some other repos used in your project
    }
}


Option 2: DependencyResolutionManagement

// settings.gradle file
dependencyResolutionManagement {
    // Example flag set, may be different in your project setup
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven("https://jitpack.io")
        // some other repositories used in your project
    }
}

Add Proxi.cloud SDK required dependencies

Next step is to add Proxi.cloud SDK dependencies to your project’s application level build.gradle file. Depending on your project’s setup you can define libraries’ packages and versions directly in build.gradle file or in a separate libs.versions.toml file and then just link to them.

As Proxi.cloud SDK relies heavly on play-services-location and ads-identifier libraries it is required to add them as well.

  • play-services-location - used for geofencing and acquiring location
  • ads-identifier - required to access Advertising Identifier

How to implement:

Option 1: Direct way

  // App level build.gradle, usually found in path: project_directory/app/build.gradle
  dependencies {
      // Proxi.cloude SDK
      implementation("cloud.proxi.sdk:cloud.proxi.sdk:2.7.26")
      // Required play services dependencies
      implementation("com.google.android.gms:play-services-ads-identifier:18.1.0")
      implementation("com.google.android.gms:play-services-location:21.3.0")
  }


Option 2: Libs.versions.toml

Define Proxi.cloud SDK dependency in libs.versions.toml file.

[versions]
# Proxi.cloud SDK version
proxiCloudSdkVersion = "2.7.26"
# play services ads identifier and location versions
adsIdentifierVersion = "18.1.0"
playServicesLocationVersion = "21.3.0"

[libraries]
# Proxi.cloud SDK
cloud-proxi-sdk = { group = "cloud.proxi.sdk", name = "cloud.proxi.sdk", version.ref = "proxiCloudSdkVersion" }
# play services ads identifier and location
ads-identifier = { group = "com.google.android.gms", name = "play-services-ads-identifier", version.ref = "adsIdentifierVersion" }
play-services-location = { group = "com.google.android.gms", name = "play-services-location", version.ref = "playServicesLocationVersion" }

Then add your dependency, similarly to the direct aproach. The difference is that we just link to the definition from libs.versions.toml file.

  // App level build.gradle, usually found in path: project_directory/app/build.gradle
  dependencies {
    // Proxi.cloude SDK
    implementation(libs.cloud.proxi.sdk)
    // Required play services dependencies
    implementation(libs.ads.identifier)
    implementation(libs.play.services.location)
  }

Set Manifest Permissions

As Proxi.cloud SDK’s primary purpose is to gather location based data it is necessary for an app to add the following permissions:

ACCESS_FINE_LOCATION is required in your manifest for location capabilities to work.

ACCESS_COARSE_LOCATION Since Android 12 user must be provided with an option to opt in for non-precise location.

Important!

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

ACCESS_BACKGROUND_LOCATION required to access location even if app is in background, needed for geofencing to work properly.

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 WiFi scanning.


Example setup for permissions in AndroidManifest.xml file.

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

    <!-- Required for Proxi.cloud SDK to enable location powered capabilities like geofencing and WiFi scanning -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>

    <!-- Required for Proxi.cloud SDK to scan WiFi networks -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>

    <!-- Required for Proxi.cloud SDK jobs -->
    <uses-permission android:name="android.permission.WAKE_LOCK"/>

    <!-- Rest of the manifest file -->

Initiate Proxi.cloud SDK

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

import cloud.proxi.ProxiCloudSdk;

class ExampleApp : Application() {

    override fun onCreate() {
        super.onCreate();
        // Init Proxi.cloud SDK
        // Replace "API_KEY" with a key provided to you by Proxi.cloud
        ProxiCloudSdk.create(this, "API_KEY");
    }
}

If you didn’t already extend Application class, it is required to link it in AndroidManifest.xml file. Inside application tag set value of android:name to the class that extends Application. ExampleApp in this case.

<!-- AndroidManifest.xml file -->
 <application
    android:name=".ExampleApp"
    >

Important!

Proxi.cloud SDK collects Advertising Identifier only if setGdprConsent is set to true.

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().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().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.

Report custom events

Proxi.cloud SDK allows application developers 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().reportEvent("product_viewed", "{'\"brand\":\"Awesome Brand\",\"name\":\"Awesome Product\",\"product_id\":1337}");