.. _installation_android:

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-min-version| (|android-min-api|).

EU Cloud Site
^^^^^^^^^^^^^

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

.. tabs::
    .. code-tab:: java Android (Java)
       :caption: Android (Java)

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

    .. code-tab:: kotlin Android (Kotlin)
       :caption: Android (Kotlin)

        val apptimizeAppKey = "YOUR_APP_KEY"
        apptimizeOptions: ApptimizeOptions = ApptimizeOptions()
        apptimizeOptions.setServerRegion(ApptimizeOptions.ServerRegion.EUCS)
        Apptimize.setup(context, apptimizeAppKey, apptimizeOptions)


SDK Installation
^^^^^^^^^^^^^^^^

Before installing the SDK, `sign in <https://apptimize.com/admin/>`_ to
the Apptimize dashboard and select one of your apps on the top
navigation menu. Then, go to the `INSTALL` tab and choose the `Android
/ Android TV / Amazon Fire TV / Wear OS` platform. 

.. figure:: ../_res/graphics/main-menu.install.1.png

.. seealso:: :ref:`app_creation`

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
--------------

Sign in to your Apptimize dashboard and download the Apptimize Android SDK
installation package. In Android Studio, add the SDK as a dependency to your
project.

.. seealso::

   Android Studio Documentation:
      - `Adding a AAR or JAR package as a dependency <https://developer.android.com/studio/projects/android-library>`_

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>[5.0.0,)</version>
      </dependency>

   If using Android Studio with the Maven Plugin, update the
   `dependencies` block in your :file:`build.gradle` file to include the following `implementation` configuration
   to automatically get the latest version of Apptimize:

   AAR format::

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

   JAR format::

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

     
.. admonition:: The JAR format is deprecated

   The JAR format is deprecated and will be removed in one of the future releases.

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 :code:`Apptimize.setup()` from either your :code:`Application`
   subclass (if you have one) or all of your activities' :code:`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 <https://apptimize.com/admin/settings/apps>`_.
   We recommend that :code:`Apptimize.setup()` be called on the main thread, or
   in some other manner that ensures :code:`Apptimize.setup()` completes before
   the Application's :code:`onCreate()` method completes.

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 :code:`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 :ref:`Integration Kits <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.

.. image:: android-installation/Android_TV_Targeting.png

See Android Developer Documentation for more detail about `UI Mode. <https://developer.android.com/reference/android/app/UiModeManager.html#getCurrentModeType()>`_

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."

.. image:: android-installation/Fire_TV_Targeting.png

Wear OS
-------

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

.. image:: android-installation/Wear_OS_Targeting.png

.. include:: ../_res/replace/common.txt