Android SDK - Basic implementation

  1. System Requirements
  2. SDK Initialization
    1. Import the Library
    2. Initialize the SDK in All Activities
    3. Configure the SDK
    4. Update the manifest
    5. Advanced Settings

1. System Requirements

The R1 Connect SDK supports all mobile and tablet devices running Android 2.3 and above. Google Play Services must be 4.0 or above. We have two different SDK versions that support Google Play Services <6.5 and ≥6.5. Please ensure that you download the version that best applies to your application.

Known Incompatibilities:

  • Proguard Java Optimizer breaks the Connect SDK and prevents data from being sent back to our servers.

2. SDK Initialization

a. Import the library to your project

Please start by downloading the demo project: git clone https://github.com/radiumone/r1-connect-demo-Android

Copy SdkLib/LibR1Connect.jar into the libs directory of your project. All mobile and tablet devices running Android 2.3. and above are supported.

If you have not registered your application in R1 Connect, please do so now.

In Android studio, the build.gradle should include the library, android-support-library-v4 library and Google Play Services as a dependency.

dependencies {
   compile files('libs/LibR1Connect.jar')
   compile 'com.android.support:support-v4:20.+'
   compile ‘com.google.android.gms:play-services:4.3.+'
}

b. Initialize the SDK in all Activities

The following steps will explain how to integrate R1 Connect to enable event tracking.

Import the emitter in all your application activities:

import com.radiumone.emitter.R1Emitter;

And override onStart and onStop methods for each activity:

@Override
protected void onStart() {
    super.onStart();
    R1Emitter.getInstance().onStart(this);
}

@Override
protected void onStop() {
    super.onStop();
    R1Emitter.getInstance().onStop(this);
}

Create a class that extends the Application class (or use an existing one), and initialize the SDK in its onCreate method:

package com.example.yourpackagename; 
import com.radiumone.emitter.R1Emitter; 
import android.app.Application;

public class TestApplication extends Application{
@Override
    public void onCreate() {
        super.onCreate();
        R1Emitter.getInstance().connect(this); 
    }
}

c. Configure the SDK

To configure how the library will be used in your project you will need to create a file called r1connect.properties in the assets directory of your project.

app_id=<YOUR APPLICATION_ID> 

#enable or disable cookie mapping. Default is false. Setting this first party cookie will enable RadiumOne to be effective in targeting the user for advertising campaigns run on behalf of the Publisher. Only enable this setting if you plan to run advertising with RadiumOne.
cookieMapping=false

4. Set Configuration Options

#enable deferred deep linking. Value is the app's registered URI scheme.
deferred_deeplink_scheme=value
#default value of analytics is set to false. Set this flag to true to enable analytics. analytics.enable=true #allow location tracking by gps analytics.enable_gps=false #location update timeout for analytics sdk. Default 600 sec analytics.location_update_time=600 #location update distance for analytics sdk. Default 100 meters analytics.location_update_distance=100 #allow location tracking in background for analytics sdk. Default false analytics.location_in_background=false #prevent location tracking for analytics sdk analytics.disable_sdk_location=false ##PUSH SETTINGS push.client_key=<YOUR CLIENT KEY> # default value for push when application starts -- set to false to use the SDK without push push.enable=true

As you can see in the example above, it will contain the following:

• app_id – You will need to enter the App ID you received when creating your app on R1 Connect (found under Dev Tools -> Keys & Secrets)

• cookieMapping – enable or disable cookie mapping. Default is false. Setting this first party cookie will enable RadiumOne to be effective in targeting the user for advertising campaigns run on behalf of the Publisher. Only enable this setting if you plan to run advertising with RadiumOne.

• push.client_key – You will need to enter the App Key you received when creating your app on R1 Connect (found under Dev Tools -> Keys & Secrets)

• analytics.enable - set to "true" enables analytics in the SDK and otherwise disables it.

• analytics.disable_sdk_location - when set to “true” it disables the use of analytics sdk tracking location. It is useful if you want to use your own tracking location. You can pass a location object like so: R1Emitter.getInstance().trackLocation(location);

• analytics.enable_gps – when set to “true” it enables the use of device GPS to get location (only if GPS is enabled in device settings), when “false” only the network is used for analytics sdk

• analytics.location_update_time – set the timeout between location updates for analytics sdk

• analytics.location_update_distance – set the change in distance for location updates for analytics sdk

• analytics.location_in_background – set whether or not the location is allowed in analytics sdk to be sent while the app is in the background

• advertising_enabled – set whether or not the application is displaying advertisements. A value of true prevents the SDK from accessing the Advertising Id to comply with Google's advertising policy when advertisements are served within the application (outside of the SDK).

• deferred_deeplink_scheme – enable deferred deeplinking, value is the app registered scheme.

d. Update the manifest

In your manifest, add the permissions below:

    <uses-permission android:name="android.permission.INTERNET" /> 
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> 
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> 
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Properly declare your application class:

<application
    android:name="com.example.yourpackagename.TestApplication" 
    android:allowBackup="true"
    …
    <service android:name="com.radiumone.emitter.location.LocationService"/>
</application>

e. Advanced Settings

The following is a list of configuration parameters for the R1 Connect SDK, most of these contain values that are sent to the tracking server to help identify your app on our platform and to provide analytics on sessions and location.

appName

The application name associated with emitter. By default, this property is populated with the package name of the application. If you wish to override this property, you must do so before making any tracking calls.

R1Emitter.getInstance().setApplicationName("customApplicationName");

appId

The application identifier associated with this emitter. By default, this property is null. If you wish to set this property, you must do so before making any tracking calls. Note that this is not your app's bundle id (e.g. com.example.appname).

R1Emitter.getInstance().setApplicationUserId("12345");

appVersion

The application version associated with this emitter. By default, this property is populated with the android:versionName= string from the application AndroidManifest.xml. If you wish to override this property, you must do so before making any tracking calls.

R1Emitter.getInstance().setAppVersion("1.0");

sessionTimeout

Indicates how long, in seconds, the application must transition to the inactive or background state before the tracker automatically indicates the start of a new session. When this happens and the app becomes active again it will set sessionStart to true. For example, if this is set to 30 seconds, and the user receives a phone call that lasts for 45 seconds while using the app, upon returning to the app the sessionStart parameter will be set to true. If, on the other hand, the phone call lasts 10 seconds, sessionStart will not be modified. By default, this is 30 seconds.

R1Emitter.getInstance().setSessionTimeout(30);

applicationUserID

Optional current user identifier.

R1Emitter.getInstance().setApplicationUserId("12345");

Next step: Event Tracking 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk