Integration

You can sign up for a new account online and integrate the SDK in your mobile app with 10 easy steps, all within 10 minutes.

[success] Just give me the code, LotaData!

If you're like us, itching to skip this guide and get your hands on the sample code, we have a sample project just for you. Feel free to clone on Github.

Compatibility

LotaData SDK for Android is broadly compatible with older versions of Android. The SDK expects you mobile device to have a GPS sub-system. Devices with only A-GPS are not supported.

[alert] Compatibility

The SDK is compatible with Android 2.3.x (API level 9) and above.

Step 1: Sign up for an account

You need to sign up for an account with LotaData.

During the sign up process, you'll be asked for certificate's SHA-1 fingerprint and app's package name.

[alert] Instruction

The app's package name and SHA-1 fingerprint must always be submitted as a pair. Please do not send one or the other.

You may send as many pairs of package name and fingerprint as you like i.e. there are no restrictions or limitations in our cloud. You may also send us separate pairs of package name and SHA-1 fingerprint for debug and release versions of the same app.

To retrieve your SHA-1 fingerprint, please follow the below steps:

  1. Locate your release certificate keystore file. There is no default location or name for the release keystore. If you don't specify one when you build your app for release, the build will leave your .apk unsigned, and you'll have to sign it before you can publish it. For the release certificate, you also need the certificate's alias and the passwords for the keystore and the certificate. You can list the aliases for all the keys in a keystore by entering:

     keytool -list -keystore your_keystore_name
    

    Replace your_keystore_name with the fully-qualified path and name of the keystore, including the .keystore extension. You'll be prompted for the keystore's password. Then keytool displays all the aliases in the keystore.

  2. Enter the following at a terminal or command prompt:

     keytool -list -v -keystore your_keystore_name -alias your_alias_name
    

    Replace your_keystore_name with the fully-qualified path and name of the keystore, including the .keystore extension. Replace your_alias_name with the alias that you assigned to the certificate when you created it.

You should see output similar to this:

Alias name: <alias_name>
Creation date: Feb 02, 2013
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Android Debug, O=Android, C=US
Issuer: CN=Android Debug, O=Android, C=US
Serial number: 4cc9b300
Valid from: Mon Feb 02 08:01:04 UTC 2013 until: Mon Feb 02 18:05:04 PST 2033
Certificate fingerprints:
    MD5:  AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6B:AC:F9
    SHA1: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75
    Signature algorithm name: SHA1withRSA
    Version: 3

The line that begins with SHA1 contains the certificate's SHA-1 fingerprint. The fingerprint is the sequence of 20 two-digit hexadecimal numbers separated by colons.

After you enter your package name and fingerprint, go ahead and submit the form online. The confirmation email will include the link to download the SDK.

Step 2: Download and install the SDK

If for any reason you are unable to find the download link, you can always get the latest LotaData SDK here.

Download LotaData SDK and include it in your project libs folder. Define the dependency for our SDK in your app module build.gradle file.

[alert] build.gradle file

Your project should have two gradle files: one for the app module, and one for the project. Edit the app module file to include the SDK.

dependencies {
    implementation project(':lotadata-sdk-latest')
    ...
}

Step 3: Configure Google Dependencies

LotaData SDK makes use of Google location services and related APIs. Please include the below dependencies in your gradle file.

dependencies {

    compile 'com.google.android.gms:play-services-ads:15.0.1'
    compile 'com.google.android.gms:play-services-location:15.0.1'
    compile 'com.google.android.gms:play-services-awareness:15.0.1
    compile 'com.google.maps.android:android-maps-utils:0.5+'
    ...
}

Step 4: Get your Google API key

You will need to add your Google API key and configure the below meta-data in AndroiManifest.xml . You can sign up for Google API credentials here

    <meta-data android:name="com.google.android.awareness.API_KEY"
    android:value="YOUR_GOOGLE_API_KEY" />

    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_GOOGLE_API_KEY" />

    <meta-data
    android:name="com.google.android.nearby.messages.API_KEY"
    android:value="YOUR_GOOGLE_API_KEY" />

Step 5: Fix your Proguard rules

Some projects include Proguard for bytecode optimization. While this can reduce the footprint of your app, you will need to be ensure that Proguard does not interfere with the SDK.

[alert] Proguard Configuration

If you are using Proguard in your project, please add the below lines to your Proguard configuration file proguard-rules.pro .

  • -keep class com.lotadata.moments.** { *; }

Step 6: Configure the SDK

You can configure the behavior of the SDK by providing the below metadata.

Collect contextual data

If you would like the SDK to collect and transmit contextual geo-data, you should include the below configuration in the AndroidManifest.xml file.

        <!--Enables SDK to collect context awareness data. Disabled by default. -->
        <meta-data
        android:name="com.lotadata.moments.ENABLE_CONTEXT_AWARE"
            android:value="boolean" />

Persist after app close

If you would like the SDK to continue to collect geo-data after the mobile app is closed, you should include the below configuration in the AndroidManifest.xml file.

        <!--Enables SDK to keep running even when app is closed. Disabled by default. -->
        <meta-data
            android:name="com.lotadata.moments.KEEP_SERVICE"
            android:value="boolean" />

Collect background data

If you would like the SDK to continue to collect geo-data when the mobile app is in the background, you should include the below configuration in the AndroidManifest.xml file.

        <!--Enables SDK to collect device data only when app is in foreground. Enabled by default. -->
        <meta-data
            android:name="com.lotadata.moments.FOREGROUND_ONLY"
            android:value="boolean" />

Show/Hide 'Privacy Policy' panel

If you would like the SDK to show our Privacy Policy Panel, you should include the below configuration in the AndroidManifest.xml file.

        <!--Enables SDK to show device LotaData's Privacy Policy. Enabled by default. -->
        <meta-data
            android:name="com.lotadata.moments.SHOW_PRIVACY_POLICY"
            android:value="boolean" />

Step 7: Enable app permissions

Marshmallow and above (API level 23+) expect permissions to be requested at run-time. You can do so by adding the below code into your main activity class.

    private Moments mMomentsClient;
    protected String[] mPermissions = {Manifest.permission.ACCESS_FINE_LOCATION, Manifest.permission.ACCESS_COARSE_LOCATION};


    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        ...

        checkPermissionsAndLaunch();
    }

    protected void checkPermissionsAndLaunch() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
            if(!hasPermissions(this, mPermissions)){
                ActivityCompat.requestPermissions(this, mPermissions, PERMISSIONS_REQUEST);
            }
        }
        initializeLotaDataSDK();
    }

    private static boolean hasPermissions(Activity activity, String... permissions) {
        if (activity != null && permissions != null) {
            for (String permission : permissions) {
                if ((ActivityCompat.checkSelfPermission(activity, permission) != PackageManager.PERMISSION_GRANTED) ||
                        (((ActivityCompat.checkSelfPermission(activity, permission) == PackageManager.PERMISSION_DENIED) && ActivityCompat.shouldShowRequestPermissionRationale(activity, permission)))){
                    return false;
                }
            }
        }
        return true;
    }

    private void initializeLotaDataSDK() {
        //TO BE DEFINED in the step 8
    }

For more details about Network permissions, we encourage you to review the Android documentation here.

Step 8: Start the SDK

Now that the SDK has been installed, you can use the SDK methods inside Android Studio to initialise the SDK after request for run-time permissions (if needed) in your main Activity class.

    private void initializeLotaDataSDK() {
        mMomentsClient = MomentsClient.getInstance(this);
        if(mMomentsClient!=null){
            //Do something with your code!
        }
    }

Step 9: Confirm data transmission

Install your app with the LotaData SDK on an Android phone and test the device and/or the app for a couple of minutes. You will be able to immediately view the location signals and activity data sent to our cloud using Lotadata's APIs. Use the APIs to confirm that data is indeed collected and transmitted from your app to our cloud. This is an important step to validate the successful integration of LotaData SDK in your app.

Additionally, after some period of use, you will be able to access user profiles and inferred behaviors through the online visual analytics dashboard or GeoDash

[warning] Recommendation

We recommend using at least 10 devices at this evaluation phase.

Step 10: Stop the SDK

To stop the SDK from collecting data, use the disconnect method in the onDestroy Activity method.

    if (mMomentsClient != null) {
        mMomentsClient.disconnect();
    }

Questions?

We are eager to hear from you and happy to share best practices for integrating the SDK. There are many ways for you to reach us:

But first, please sign up for an account with LotaData so that we may send you the link to download our SDK.


Was this helpful? Yes, thanks! Not really

results matching ""

    No results matching ""