Android Smartwhere Integration

main-logo

The TUNE Marketing Console integration with Smartwhere extends the power of the TUNE platform to the real-world. Enabling it unlocks features such as:

  • In-store visit attribution.
  • Audience insights and segment creation based on the real-world places your app users visit and the length of their visit.
  • Proximity triggered engagements.

Smartwhere works with all existing proximity technologies, from Beacons, Geofencing and Wi-Fi, NFC and QR. Smartwhere is already helping:

  • Retail Campaigns
  • In-Store Experiences
  • Museums
  • On-site Mapping and Blue Dot
  • Events and Venues
  • Integrated Print Campaigns
  • Social Media Campaigns

The following document will walk you through the steps necessary to enable Smartwhere for your Android application.

Note: Before beginning your Smartwhere integration be sure that your TUNE account has had the Smartwhere functionality enabled. Please contact your Customer Success Manager for more information.

Android Integration

To integrate Smartwhere Proximity and Location functionality with your Android app follow these steps:

Step 1: Integrate the TUNE SDK v 4.11.1 +

Smartwhere is included in the latest TUNE SDK. Follow the TUNE Android Quick Start Guide for detailed integration instructions.

Step 2: Enable Smartwhere

Smartwhere is included in the latest TUNE SDK but is disabled by default. To enable Smartwhere call the following method after the TUNE initialization:

Tune.getInstance().enableSmartwhere();

To optionally expose your TUNE client events to Smartwhere, for example to trigger proximity engagements based on your own custom events, make the following call after enabling Smartwhere:

Tune.getInstance().enableSmartwhere();
Tune.getInstance().configureSmartwhere(new TuneSmartwhereConfiguration(){{
grantAll();
}});

Step 3: Request location permissions

If you’re using Android 6.0 (API Level 23) or higher request the end-user permission for location access, at the earliest appropriate instance in your app flow. In addition to being a requirement for enabling Smartwhere this will also allow latitude and longitude to be collected when TUNE measureSession/measureEvent methods are called.

For prior versions of Android be sure to update your AndroidManifest.xml with the necessary permissions required to enable location and proximity features.

See our Android Permissions article for more information on which specific permissions are needed for which specific features.

Disabling Tune Smartwhere Integration

If for any reason you need to disable TUNE Smartwhere SDK integration post app initialization, use the following call:

Tune.getInstance().disableSmartwhere();

  • Minimum platform versions:
    • Android - API 9 : Android 4.3 (Jelly Bean)

Google Play Services

Install the Google Play Services SDK and import it into your project in order for the SDK to collect the Google Advertising ID. If you’re using Gradle, you may choose to add only the basement library to your dependencies:

compile 'com.google.android.gms:play-services-basement:10.0.0'

Note: If you are already including the full Google Play Services library (compile 'com.google.android.gms:play-services:10.0.0') then you do not need to add the -basementsubpackage. You can use any version of Google Play Services greater than 4.0.0.

ProGuard for Android Integration

If using ProGuard, exclude the Smartwhere classes from obfuscation in your ProGuard configuration file with the following lines:

-keep class com.proximity.library.** { public protected private *; }

Android Debug Messages

When debugMode is enabled, the console log statements will additionally include messages (prefaced with “com.tune.sw_tune_android”) related to location proximity events such as the following:

com.tune.sw_tune_android I/ProximitySDK: ProximityService version: REL_17087.1
com.tune.sw_tune_android I/ProximitySDK: ConfigurationHandler: Reading Proximity Configuration class com.tune.sw_
com.tune.sw_tune_android I/ProximitySDK: Defaulting persisted config.
com.tune.sw_tune_android I/ProximitySDK: ProximityService Stopping!  Credentials are not set
com.tune.sw_tune_android I/ProximitySDK: Defaulting SWCreds
com.tune.sw_tune_android I/ProximitySDK: Defaulting persisted config.
com.tune.sw_tune_android I/ProximitySDK: Config Command received
...
...
com.tune.sw_tune_android I/ProximitySDK: GeofenceServerRunner - starting.
com.tune.sw_tune_android I/ProximitySDK: GeofenceServerRunner - got 3 fences.
com.tune.sw_tune_android I/ProximitySDK: GeofenceServerRunner - adding 3 fences.
com.tune.sw_tune_android D/ProximitySDK: GeofenceServerRunner - rescheduling geofence update in 86400000
com.tune.sw_tune_android I/ProximitySDK: (geofence-transition) received geofence event id=0
...
...
com.tune.sw_tune_android I/ProximitySDK: handleGeofenceTranstionIntent: Received GEOFENCE_TRANSITION_ENTER from google for 1032545 handling enter.
com.tune.sw_tune_android I/ProximitySDK: geofence-transition: Entered fence 1032545 but needs update...
com.tune.sw_tune_android I/ProximitySDK: Transition 1032545 Eiffel Tower withTrigger 20
com.tune.sw_tune_android I/ProximitySDK: mTriggerFenceDiscovery - starting.
...

Android Troubleshooting Common Issues

  • Android: Make sure AndroidManifest.xml includes uses-permission tag for ACCESS_FINE_LOCATION
  • Android: Make sure build.gradle includes compile entry for gms:play-services-location
  • Android: Make sure location permission is being requested -- e.g. ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, 102);
  • Make sure location access permission is granted when the dialog shows up. This permission can also be modified from the system Settings.
  • Make sure appropriate geofences, beacons, etc. have been setup on Smartwhere.
  • Check the TUNE TMC AA dashboard "Test Logs" report since this report can show near real time log records.

No Comments

Leave a reply