If you have any problem regarding SDK integration or need more informations, email us at support@singlespot.com.

Migration from previous versions

Our 2.+ SDK versions includes many features related to GDPR, and some minor changes in its initialisation were required. If you update from a previous version, please follow this guide from 4.2. Initialization and be sure to read 6. Migration from version < 2.0

1. Link to the SDK with Maven

Open your build.gradle file located at the root of your project (its name can be followed in grey by Project: [name of your project] depending on the display mode you are using). Add the Maven configuration below, using your provided Singlespot Maven repository credentials. Please make sure you add the configuration to the allprojects section rather than the buildscript section.

buildscript {
    repositories {
        jcenter()
        // Please do not place the configuration here
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:3.2.0'
    }
}
allprojects {
    repositories {
        jcenter()
        maven {
            url "http://sdk.singlespot.com/artifactory/SPTProximityKit"
            credentials {
                username = "USERNAME"
                password = "PASSWORD"
            }
        }
        // ...
    }
}

Open your app/build.gradle file (its name can be followed in grey by Module: app depending on the display mode you are using). Add the following dependency:

dependencies {
    // ...
    compile 'com.sptproximitykit:SPTProximityKit:2.+'
}

2. Synchronize your Gradle files

After having changed your Gradle files, perform a project sync by clicking Sync Now. If you encounter any dependency issues, don't hesitate to clean your Android Studio caches by choosing Invalidate Caches/Restart from the File Menu.

3. Add your credentials into your app's AndroidManifest.xml

Add your API key and API secret into your app's AndroidManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name">
<activity android:name=".MainActivity">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>

<meta-data
android:name="com.sptproximitykit.ApiKey"
android:value="YOUR_API_KEY"
/>
<meta-data
android:name="com.sptproximitykit.ApiSecret"
android:value="YOUR_API_SECRET"
/>

</application>
</manifest>

4. SDK integration

4.1. Importation

Add the following import statements into your MainActivity.java file

import android.os.Build;
import android.support.annotation.NonNull;
import android.support.annotation.RequiresApi;

import com.sptproximitykit.SPTProximityKit;

4.2. Initialization

Add the SDK initialization code at the beginning of your onCreate method in your Launcher Activity:

@Override
protected void onCreate(Bundle savedInstanceState) {

    SPTProximityKit.Mode mode = SPTProximityKit.Mode.serverBased;
    // SPTProximityKit.Mode mode = SPTProximityKit.Mode.onDemand;

    SPTProximityKit.init(this, mode, true); // The last parameter is isCMP.

    // your code
}

mode may take the following values:

isCMP is a boolean that sets if you want to use Singlespot as your Consent Management Platform (CMP). (See 5. User consent management)

4.3. Mode OnDemand

In this mode you must trigger the location authorization request (for exemple once your user signed in or at the end of the onboarding). Do not forget to do so by calling:

SPTProximityKit.requestLocationPermissions(activity);

You also need to override the onRequestPermissionsResult method as follows:

@RequiresApi(api = Build.VERSION_CODES.M)
@Override
    public void onRequestPermissionsResult(int requestCode, @NonNull String permissions[], @NonNull int[] grantResults) {
    SPTProximityKit.updatePermission(activity, permissions);
}

If you want to handle the location authorizations yourself somewhere else and therefore never call this method you are free to do so, but do not forget to ask for always authorizations.

4.4. Location request configuration

If the SDK handles the location request, you can customize its behaviour from the Configuration section of the SDK menu on the left navigation panel.

5. Consent management

The Singlespot SDK provides a flexible Consent Management Platform (CMP) that you may use if you need to. It follows the IAB framework, and is GDPR compliant for location purposes. It can work with any other CMP with minor adjustment, and is remotely configurable via the Singlespot dashboard (to be released soon, in the meantime we will configure everything for you).

If you do not wish to use the Singlespot CMP, you can go to 5.5. Integrating with a 3rd party CMP

5.1. Initial consent request

If the value true is set in the SDK initialisation method for the parameter isCMP, then a webView will be displayed on the next launch of the application, listing:

The list of purposes and vendors will be configurable from the Singlespot dashboard.

5.2. Consent management

In order to allow the users to manage their consent after the first request, you need to call the following SDK method from wherever is the most appropriate in your application:

SPTProximityKit.openCMPSettings(activity);

Doing so opens a 'settings' webView that will allow to switch on or off purposes and to see all the vendors.

5.3. Accessing consents

The Singlespot CMP follows the IAB Framework, and therefore writes all IAB related consents to strings stored in the NSUserDefaults under the keys IABConsent_ConsentString, IABConsent_ParsedPurposeConsents, and IABConsent_ParsedVendorConsents (as per IAB documentation). These consents can be read directly by your application or by any SDK, but the Singlespot SDK also allows you to access these strings with the following methods:

SPTProximityKit.getIABConsentString(this);
SPTProximityKit.getIABParsedPurposeConsents(this);
SPTProximityKit.getIABParsedVendorConsents(this);

You can also access consents status for a specific purpose or vendor. If you wish to access these consents for a purpose or a vendor which is present in IAB's vendorlist (https://vendorlist.consensu.org/vendorlist.json), you can use the following methods, using the id provided in the vendorlist:

SPTProximityKit.isConsentGivenForIABVendor(this, int vendorId)
SPTProximityKit.isConsentGivenForIABPurpose(this, int purposeId)

If you want to get the consent status for a custom purpose or vendor, you can use the following methods with the corresponding key that has been provided by our team at CMP setup:

SPTProximityKit.isConsentGivenForCustomVendor(this, String vendorKey);
SPTProximityKit.isConsentGivenForCustomPurpose(this, String purposeKey);

Custom vendors and purposes consents are also stored in the DefaultSharedPreferences under the same keys, and can therefore be accessed by any 3rd party SDK with the right key.

Aliases have been defined to get the consent value for the two non-IAB purposes that are required by Singlespot (as mentionned in 5.5 below):

SPTProximityKit.getGeoMediaConsent(this);
SPTProximityKit.getGeoDataConsent(this);

5.4. Callbacks

If you need callbacks for the various events related to the CMP, you can also pass your implementation of a CMPEventsHandler as an optional argument to the SDK initialisation method, as follows:

final CMPEventsHandler cmpEventsHandler = new CMPEventsHandler();
SPTProximityKit.init(this, mode, true, cmpEventsHandler);

You can declare your implementation of CMPEventsHandler as follows:

private static class CMPEventsHandler implements SPTProximityKit.CMPEventsHandler {
  @Override
    public void onCMPDisplay() {
        // your code
    }

    @Override
    public void onCMPConsentsChanged() {
        // your code
    }

    @Override
    public void onCMPCompletion(boolean didDisplayCMP, Error error) {
        // your code
    }
}

5.5. Integrating with a 3rd party CMP

If the value false is set in the SDK initialisation method, you need to use a 3rd party CMP. To be compatible with Singlespot SDK, it must get consent for the following two purposes (translation and description will be provided on demand):

The SDK will read the vendor consent from the IABConsent_ConsentString directly, but as the above mentioned purposes are not part of the IAB framework, consent for these need to be handled differently.

You can set consent for these two purposes using the following methods:

SPTProximityKit.setGeoDataConsent(this, Boolean isGeoDataConsent);
SPTProximityKit.setGeoDataConsent(this, Boolean isGeoMediaConsent);

You can also store them as boolean in the sharedPreferences, like the IABConsent_ConsentString, under a key that must be provided in the Consent section of the Singlespot dashboard.

Please note

To the extent possible, please let the Singlespot SDK handle its consents checks and activate itself when sufficient consents are granted. Simply setting the consents as mentionned above will be enough to know when to be switched on or off.

6. Migration from version < 2.0

If you have any question, feel free to contact us at support@singlespot.com.