.. _setup:

SDK setup
=========

Modify your manifest
--------------------

.. Warning:: You don't need to do this if you are using Gradle

Add this to your manifest file:

.. code-block:: xml

    <uses-permission android:name="android.permission.INTERNET"/>
    <!-- This allow us to know when there's connectivity to send the events -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <!-- Used to get info like imei, etc. to create unique device identifiers -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
    <!-- Used to get mac address; optional -->
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>

    <receiver android:name="com.scopely.analytics.AnalyticsDispatcher"/>

    <receiver android:name="com.scopely.analytics.ConnectivityChangeReceiver">
      <intent-filter>
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE"/>
      </intent-filter>
    </receiver>

Initialize the SDK
------------------

This has to be done **once** in the ``android.app.Application`` instance of your app:

.. code-block:: java

    @Override public void onCreate() {
      Analytics.initialize(this, "API-KEY-HERE");
    }

Make sure to put this in the application instance rather than in the main activity.
Also make sure the ``android:name`` attribute of the ``application`` tag points to this class.

Track events
------------

Once analytics has been initialized in the  you can track events using the
``com.scopely.analytics.Tracker`` class. Some examples:

.. code-block:: java

    import static com.scopely.analytics.Tracker.*;

    // Track a transaction where user buys a scratch using 10 coins:
    trackGameTransaction("Buy", "Buy scratch",
                         withTransactions("scratch", 1).and("coins", -10));

    // track an IAP of 3.99 USD to buy an item whose sku is `free_spanks_sku`
    trackPayment(withAmountUS(399)
                 .amountLocal(7000)
                 .localCurrencyType("COP")
                 .special("free_spanks", "Free spanks")
                 .storeSku("free_spanks_sku")
                 .gameSku("free_death_spanks"));

    // Track custom events with extras `{foo: 1, bar: "qux"}`
    track("event_name", withExtras("foo", 1).and("bar", "qux"));



Profile properties
------------------

Profile properties are user properties that are attached to all events you track. You can edit
these properties by getting an instance of ``ProfilePropertiesEditor``:

.. code-block:: java

    ProfilePropertiesEditor profilePropertiesEditor = Analytics.getInstance().getProfilePropertiesEditor();

Then you can use any of the provided methods to update these properties; for instance
the age of the user:

.. code-block:: java

    profilePropertiesEditor.setAge(age);

Other available methods are: ``setGender(Gender)``, ``setUserId(String)``,
``setFacebookId(String)``, ``setPushEnabled(boolean)``, ``setPushToken(String)``,
``setStore(String)`` and ``setCustomProperty(String, String)``.

Dispatch events on device boot
------------------------------

It could be desirable to dispatch all cached events on device boot. In order to do so you could
register the analytics dispatcher in your manifest this way:

.. code-block:: xml

    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>

    <receiver android:name="com.scopely.analytics.AnalyticsReceiver">
      <intent-filter>
        <action android:name="android.intent.action.BOOT_COMPLETED"/>
      </intent-filter>
    </receiver>

Optionally, if you already have a boot receiver, you can call the ``AnalyticsReceiver`` directly:

.. code-block:: java

    // inside your boot receiver
    Intent analyticsDispatcher = new Intent(context, AnalyticsDispatcher.class);
    context.sendBroadcast(analyticsDispatcher);