Setting up your app

β€‹πŸ”© Minimum requirements

First, check out if you fulfill the SDK minimum requirements.

Requirement

Version

Minimum Android SDK version

Android API 16

Android Support Library v4

28+

Google Play Services Ads

12.+

Google Play Services Location

12.+

If your project is using AndroidX you will need to make sure Jetifier is enabled in your gradle.properties file:

gradle.properties
gradle.properties
android.useAndroidX=true
android.enableJetifier=true

β€‹πŸ“² Dependencies

In your app-level build.gradle file, add the following dependencies.

Android X
Android Support
Android X
dependencies {
// Required
implementation 'com.inlocomedia.android:android-sdk-engagement:5.5.0'
// Google Play Services
implementation 'com.google.android.gms:play-services-location:17.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:17.0.0'
​
// Compatibility with Support Library
implementation 'androidx.legacy:legacy-support-v4:1.0.0'
}
Android Support
dependencies {
// Required
implementation 'com.inlocomedia.android:android-sdk-engagement:5.5.0'
// Google Play Services
implementation 'com.google.android.gms:play-services-location:16.0.0' // You can use versions from 12.0.0 up to 16.0.0
implementation 'com.google.android.gms:play-services-ads-identifier:16.0.0' // You can use versions from 12.0.0 up to 16.0.0
​
// Support Library
implementation 'com.android.support:support-v4:28.0.0'
}

After updating your app-level build.gradle, the project must be synced for the changes to take effect.

β€‹πŸ“„Update Android manifest

Add the following <uses-permission> tags inside the <manifest> tag of your AndroidManifest.xml file.

AndroidManifest.xml
AndroidManifest.xml
<manifest>
<!-- Required for connectivity access -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- Required for location services -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- Improves location accuracy and battery consumption -->
<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION"/>
<!-- Allows the SDK to restart itself after the device is rebooted -->
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
<!-- For apps targeting Android 10 (29) and higher only -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION"/>
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
</manifest>

If you want, take a look at why we ask these permissions:

β€‹βž‘Add config file to your project

The Inloco SDK initialization relies on the presence of an inloco.xml file in the main/res/values directory of your project.

Please modify the inloco_app_id field and add it to the main/res/values directory in your Android project.

β€‹πŸ§™β™‚Tip: There is a button on integration wizard where you can download inloco.xml file with your app_id already filled.

inloco.xml
inloco.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- Your App id-->
<string name="inloco_app_id" translatable="false">YOUR_APP_ID</string>
​
<!-- Whether SDK logs are enabled -->
<bool name="inloco_log_enabled">true</bool>
​
<!-- Whether visits tracking is enabled by default after SDK initialization -->
<bool name="inloco_visits_enabled_by_default">true</bool>
​
<!-- Whether the user needs to provide privacy consent -->
<bool name="inloco_privacy_consent_required">false</bool>
</resources>

β€‹πŸ§ Note: Remember to replace YOUR_APP_IDwith the identifier of the application you created on your dashboard. Click here if you don't know your App ID or if you don't know what App ID is.

The complete list of possible customization keys is shown below.

Key

Description

Type

Required

inloco_app_id

Your Application ID.

string

β€‹βœ”

inloco_log_enabled

Whether logs are enabled.

boolean (true)

β€‹βœ–β€‹

inloco_visits_enabled_by_default

Whether visit tracking is enabled by default during the SDK initialization.

boolean (true)

β€‹βœ–

inloco_privacy_consent_required

Whether the user needs to provide privacy consent for the SDK to be initialized.

boolean (false)

β€‹βœ–

inloco_background_wakeup_enabled

Whether background wakeup is enabled.

boolean (true)

β€‹βœ–

β€‹πŸš€ Initializing the SDK

Inside the onCreate method of your Application class, insert the following code to initialize the Inloco SDK.

Kotlin
Java
Kotlin
import com.inlocomedia.android.common.InLoco
​
class CustomApplication : Application() {
override fun onCreate() {
super.onCreate()
//Initializes the Inloco SDK
InLoco.init(this)
}
}
Java
import com.inlocomedia.android.common.InLoco;
​
public class CustomApplication extends Application {
​
@Override
public void onCreate() {
super.onCreate();
​
//Initializes the Inloco SDK
InLoco.init(this);
}
}

β€‹πŸ§™Tips: For instructions on how to create your own implementation of the Application class, please check the official Android documentation.

If the SDK was initialized properly, your Logcat 😺 output will contain the following logs. The table identifies the main elements required for Inloco to work properly. When a requirement is not met, a description is shown with information regarding what this requirement enables and what must be done for it to be satisfied.

Logcat
Logcat
I/InLocoMedia: In Loco Engage 5.5.0 is running
I/InLocoMedia: In Loco 5.5.0 is running
I/InLocoMedia: Device advertising Id: <YOUR-DEVICE-ADVERTISING-ID>
I/InLocoMedia:
╔══════════════════════════════════════════════════════════════════════════════════════════╗
β•‘ In Loco Engage Diagnostics β•‘
╠══════════════════════════════════════════════════════════════════════════════════════════╣
β•‘ Requirements β•‘ Status β•‘ Troubleshooting β•‘
╔══════════════════════════════════════════════════════════════════════════════════════════╗
β•‘ Wifi enabled β•‘ Yes β•‘ β•‘
β•‘ Location enabled β•‘ Yes β•‘ β•‘
β•‘ Internet available β•‘ Yes β•‘ β•‘
β•‘ Permissions granted β•‘ Yes β•‘ β•‘
β•‘ Push provider set β•‘ Yes β•‘ β•‘
β•‘ Privacy consent given β•‘ Yes β•‘ β•‘
β•‘ Engage user is set β•‘ No β•‘ Set the engage user if you are using data integrations. β•‘
β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•

β€‹πŸ”§ Testing

After integrating the SDK, the wizard will wait for an event to be sent in order to validate that the integration was successful.

β€‹πŸšΆβ™‚ Request runtime permissions

The previous step started the Inloco SDK, but your application still needs to request the location permissions (i.e., ACCESS_FINE_LOCATION and ACCESS_BACKGROUND_LOCATION) to the user in order to fully unlock the location capabilities of the SDK.

We recommend that the permissions are requested as shown in the Android documentation.

β€‹πŸš§ Attention: Without the Manifest.permission.ACCESS_FINE_LOCATION, most features will not be available. It is extremely important that the user is asked for permission and that the app has a relevant reason to do so. If you are targeting Android 10, you also must ask for Manifest.permission.ACCESS_BACKGROUND_LOCATION.

​