Android / Wear OS / Android TV / Fire TV

Apptimize supports experimentation and release management on Android, Wear OS (formerly Android Wear), Android TV, and Amazon Fire TV through our Android SDK.

The Apptimize Android SDK is compatible with Android versions 5.0+ (Lollipop+ / API 21+).

EU Cloud Site

Use the ApptimizeOptions method to set your server region to EUCS if you are integrated in our EU Cloud site.

String apptimizeAppKey = "YOUR_APP_KEY";
ApptimizeOptions apptimizeOptions = new ApptimizeOptions();
apptimizeOptions.setServerRegion(ApptimizeOptions.ServerRegion.EUCS);
Apptimize.setup(context, apptimizeAppKey, apptimizeOptions);

SDK Installation

Sign in to the Apptimize dashboard. You’ll see a welcome page that asks for the name of your app. After entering all your info, you’ll see these installation instructions again.

You have three options for installing the Android SDK:

1. Android Studio
2. Maven
3. Segment or mParticle Integration Kit

Note: The Wear OS and Android TV SDKs use the same library as the Android SDK and have the same setup steps.

Android Studio

1. After you’re signed in, you’ll be able to download the Apptimize Android SDK jar file. Put it in the libs directory of your Android project. For Android Studio, make sure to right click the Apptimize SDK and select “Add as Library…” so the SDK will appear in your app’s build.gradle dependencies section.

Maven

Apptimize is hosted as a Maven repository.

1. Add the appropriate repositories.

   If using POM files:

   <repository>
     <id>apptimize-repo</id>
     <url>https://maven.apptimize.com/artifactory/repo</url>
   </repository>
   

   If using Android Studio with the Maven Plugin:

   repositories {
     maven { url 'https://maven.apptimize.com/artifactory/repo' }
   }
   

2. Add the appropriate dependencies.

   If using POM files:

   <dependency>
     <groupId>com.apptimize</groupId>
     <artifactId>apptimize-android</artifactId>
     <version>[3.0.0,)</version>
   </dependency>
   

   If using Android Studio with the Maven Plugin:

   dependencies {
     implementation 'com.apptimize:apptimize-android:3.+'
   }
   

Initializing Apptimize

In both the Android Studio and Maven setup options, you will need to handle initialization of the Apptimize SDK yourself.

1. In any files that you use Apptimize, you’ll need to add one or both of the following import statements:

   import com.apptimize.Apptimize;
   import com.apptimize.ApptimizeTest;
   

   They’ll look something like this when you’re done:

   import android.os.Bundle;
   import android.app.Activity;
   import android.view.Menu;
   import com.apptimize.Apptimize;
   import com.apptimize.ApptimizeTest;
   
   public class ToDoActivity extends Activity {
     ArrayList<String> items;
     ArrayAdapter<String> itemsAdapter;
     ListView lvItems;
     ...
   }
   

2. Next, call Apptimize.setup() from either your Application subclass (if you have one) or all of your activities’ onCreate() methods like this:

   public class ToDoActivity extends Activity {
     @Override
     protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_todo);
   
       // Insert your App Key here
       Apptimize.setup(this, "XXXxxXXxxxXXXxxXXxxxXXXxxXXxxxX");
       ...
     }
     ...
   }
   

   Replace the placeholder with your application key, which is a 31 character key that can be found on the installation instructions while logged in or in your Admin app settings. We recommend that Apptimize.setup() be called on the main thread, or in some other manner that ensures Apptimize.setup() completes before the Application’s onCreate() method completes.

3. Double check in your AndroidManifest.xml that you’ve requested the internet access permission:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
     <uses-permission android:name="android.permission.INTERNET" />
   

It should look something like this:

4. Lastly, if you have ProGuard enabled for your app, add the following to your ProGuard configuration file. These lines help ensure that programmatic tests, the Visual Editor support for newer UI elements, and our analytics SDKs integration all work properly. We recommend you add all of them for maximum capability:

   -keep class com.apptimize.** { *; }
   -keepclassmembers class * extends com.apptimize.ApptimizeTest {
     <methods>;
   }
   
   -keep class android.support.v4.app.Fragment { *; }
   -keep class android.support.v4.app.FragmentPagerAdapter { *; }
   -keep class android.support.v4.app.FragmentStatePagerAdapter { *; }
   -keep class android.support.v4.view.ViewPager
   -keep class android.support.v4.view.ViewPager$LayoutParams { *; }
   
   -keep class android.support.v7.app.Fragment { *; }
   -keep class android.support.v7.app.FragmentPagerAdapter { *; }
   -keep class android.support.v7.app.FragmentStatePagerAdapter { *; }
   -keep class android.support.v7.view.ViewPager
   -keep class android.support.v7.view.ViewPager$LayoutParams { *; }
   
   -keep class android.support.v7.widget.** { *; }
   
   -keep class android.support.v13.app.FragmentPagerAdapter { *; }
   -keep class android.support.v13.app.FragmentStatePagerAdapter { *; }
   
   -keep class com.adobe.adms.measurement.ADMS_Measurement { *; }
   -keep class com.adobe.mobile.Analytics { *; }
   -keep class com.adobe.mobile.Config { *; }
   
   -keep class com.amplitude.api.AmplitudeClient { *; }
   -keep class com.amplitude.api.Revenue { *; }
   -keep class com.amplitude.api.Identify { *; }
   
   -keep class com.google.android.gms.analytics.Tracker { *; }
   -keep class com.google.analytics.tracking.android.Tracker { *; }
   
   -keep class com.google.firebase.analytics.FirebaseAnalytics { *; }
   -keep class android.os.Bundle { *; }
   
   -keep class com.crashlytics.** { *; }
   -keep class com.flurry.android.FlurryAgent { *; }
   -keep class com.localytics.android.Localytics { *; }
   -keep class com.mixpanel.android.mpmetrics.MixpanelAPI { *; }
   -keep class com.omniture.AppMeasurementBase { *; }
   -keep class com.segment.analytics { *; }
   

Build your app to make sure that SDK was installed correctly. Verify that the SDK is loading by running your app and checking the Android logcat for the message Apptimize: Version 2.x.x.

You’ve finished the Apptimize installation and are ready to configure your first A/B experiment!

Segment or mParticle Integration Kit

You can install our Android SDK via our Segment or mParticle Integration Kits. You might want to use this option if you’re already tracking similar data with other services as you only need to send that data to Segment or mParticle once and will show up in Apptimize and other integrations with the flip of a switch.

Learn more about our Integration Kits here!

Wear OS, Android TV and Fire TV

Once the Android SDK is installed setup as described above, you will be able to execute experiments or query feature flags on any Android device where the SDK is deployed. If you want to target a specific Android OTT platform, you can do that via the Apptimize Dashboard.

Android TV

If you are looking to run an experiment on Android TV devices but don’t want the experiment to reach Android users who are running your app on other configurations (e.g. Mobile), you can use the Android UI Mode device property available in targeting. Note that this property is available in version 3.3+ of the Android SDK.

An Android UI Mode of “Television” indicates that the device has been configured for a “ten foot” experience.

See Android Developer Documentation for more detail about UI Mode.

Amazon Fire TV

To specifically target Amazon Fire TV devices, choose the Android UI Mode “Television” as described above, and also add a Device Brand filter for “Amazon.”

Wear OS

To specifically target Wear OS devices, choose the Android UI Mode “Watch” as described above