Introduction

Prerequisites

• Java Development Kit (JDK) 1.6.

• Android SDK.

• This library currently supports Android 2.3.3 and higher.

• An IDE (like Eclipse or Android Studio), with ADT installed.

Get an Application Key

Request a new application key to the Kiwi Team

Import the library

Using gradle

Include the import on your build.gradle file:

compile ('com.movile.kiwi:kiwi-sdk-android:VERSION@aar') {
    transitive = true
}

Using jar

Get the lastest version of jar:

https://nexus-android.it.movile.com/nexus/service/local/artifact/maven/redirect?r=releases&g=com.movile.kiwi&a=kiwi-sdk-android&v=VERSION&e=jar

Put the jar on your project's library folder and add to the classpath.

When using jar, you need to resolve the dependencies manually:

• com.google.android.gms:play-services-gcm:8.1.0 (or newer)

• com.google.android.gms:play-services-ads:8.1.0 (or newer)

• com.android.support:support-v4:23.1.0 (or newer)

Enabling debug logs

/adbLocation/./adb shell setprop log.tag.KIWI_SDK DEBUG

Proguard

If you are using proguard into your app, add the following configuration:

// in your build.gradle file

android {
    buildTypes {
        release {
            proguardFile 'proguard-android.pro' // for your app
            proguardFile 'proguard-kiwi.pro' // for kiwi
        }
    }
}

Create the file named proguard-kiwi.pro and add the following content:

-keepattributes Exceptions,InnerClasses,Signature,Deprecated,SourceFile,LineNumberTable,*Annotation*,EnclosingMethod

# jackson annotations must be kept
-keep public class org.codehaus.jackson.**annotate.** {
 public protected *;
}

-keep class com.movile.kiwi.**
# Kiwi Proguard Keep annotations
-keep public class com.movile.kiwi.sdk.util.proguard.* {
 public protected *;
}
###################################
# KEEP ANNOTATIONS
###################################

# @Keep specifies not to shrink, optimize, or obfuscate the annotated class
# or class member as an entry point.

-keep @com.movile.kiwi.sdk.util.proguard.Keep class * {
   public *;
}

-keepclassmembers class * {
   @com.movile.kiwi.sdk.util.proguard.Keep *;
}


# @KeepName specifies not to optimize or obfuscate the annotated class or
# class member as an entry point.

-keepnames @com.movile.kiwi.sdk.util.proguard.KeepName class *

-keepclassmembernames class * {
   @com.movile.kiwi.sdk.util.proguard.KeepName *;
}


# The following annotations can only be specified with classes.

# @KeepImplementations and @KeepPublicImplementations specify to keep all,
# resp. all public, implementations or extensions of the annotated class as
# entry points. Note the extension of the java-like syntax, adding annotations
# before the (wild-carded) interface name.

-keep        class * implements @com.movile.kiwi.sdk.util.proguard.KeepImplementations       *
-keep public class * implements @com.movile.kiwi.sdk.util.proguard.KeepPublicImplementations *

# @KeepApplication specifies to keep the annotated class as an application,
# together with its main method.

-keepclasseswithmembers @com.movile.kiwi.sdk.util.proguard.KeepApplication public class * {
   public static void main(java.lang.String[]);
}

# @KeepClassMembers, @KeepPublicClassMembers, and
# @KeepPublicProtectedClassMembers specify to keep all, all public, resp.
# all public or protected, class members of the annotated class from being
# shrunk, optimized, or obfuscated as entry points.

-keepclassmembers @com.movile.kiwi.sdk.util.proguard.KeepClassMembers class * {
   *;
}

-keepclassmembers @com.movile.kiwi.sdk.util.proguard.KeepPublicClassMembers class * {
   public *;
}

-keepclassmembers @com.movile.kiwi.sdk.util.proguard.KeepPublicProtectedClassMembers class * {
   public protected *;
}

# @KeepClassMemberNames, @KeepPublicClassMemberNames, and
# @KeepPublicProtectedClassMemberNames specify to keep all, all public, resp.
# all public or protected, class members of the annotated class from being
# optimized or obfuscated as entry points.

-keepclassmembernames @com.movile.kiwi.sdk.util.proguard.KeepClassMemberNames class * {
   *;
}

-keepclassmembernames @com.movile.kiwi.sdk.util.proguard.KeepPublicClassMemberNames class * {
   public *;
}

-keepclassmembernames @com.movile.kiwi.sdk.util.proguard.KeepPublicProtectedClassMemberNames class * {
   public protected *;
}

# @KeepGettersSetters and @KeepPublicGettersSetters specify to keep all, resp.
# all public, getters and setters of the annotated class from being shrunk,
# optimized, or obfuscated as entry points.

-keepclassmembers @com.movile.kiwi.sdk.util.proguard.KeepGettersSetters class * {
   void set*(***);
   void set*(int, ***);

   boolean is*();
   boolean is*(int);

   *** get*();
   *** get*(int);
}

-keepclassmembers @com.movile.kiwi.sdk.util.proguard.KeepPublicGettersSetters class * {
   public void set*(***);
   public void set*(int, ***);

   public boolean is*();
   public boolean is*(int);

   public *** get*();
   public *** get*(int);
}

###################################
# END - KEEP ANNOTATIONS
###################################

Configure Android Manifest

You can use the follow template to configure your app. Note: Remember to replace the values:

• <APPLICATION_KEY> with the provided Kiwi Application Key;

• <BACKUP_KEY> that must be generated on https://developer.android.com/google/backup/signup.html?&csw=1

• <PACKAGE_NAME> your app package name;

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="<PACKAGE_NAME>">

    <!--
      This user-permission is required to allow the application to send events and properties to KiwiWebService.
     -->
    <uses-permission android:name="android.permission.INTERNET"/>

    <!--
      This user-permission is optional but recommended so we can be smart about when we send data,
      and send more complete data about your users automatically.
     -->
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />


    <!--
      This user-permission is required in order to allow the application to synchronize events model KiwiWS when device wakeup.
     -->
    <uses-permission android:name="android.permission.WAKE_LOCK"/>

    <!--
     This permission is used in order to register alarms to sync user's profile with Kiwi Webservice periodically. If this permission is missing, the alarms will only be registered when the app opens
     -->
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

    <!--
      This user-permission is required to retrieve the device IMEI
      It's also used to try to retrieve programatically the device's msisdn and carrier, although this is not always possible
     -->
    <uses-permission android:name="android.permission.READ_PHONE_STATE"/>

    <!--
      This permission is required to retrieve the user's google account email
     -->
    <uses-permission android:name="android.permission.GET_ACCOUNTS" />

    <application
            android:allowBackup="true"
            android:backupAgent="com.movile.kiwi.sdk.context.KiwiBackupAgent">

        <service
            android:name="com.evernote.android.job.gcm.PlatformGcmService"
            android:enabled="true"
            tools:replace="android:enabled"/>

        <service
            android:name="com.movile.kiwi.sdk.sync.SyncJobManagerService"
            android:permission="android.permission.BIND_JOB_SERVICE" />
    
        <receiver android:name="com.movile.kiwi.sdk.receiver.AfterBootBroadcastReceiver"
                  android:permission="android.permission.RECEIVE_BOOT_COMPLETED" >
            <intent-filter>
                <action android:name="android.intent.action.BOOT_COMPLETED" />

                <category android:name="android.intent.category.DEFAULT" />
            </intent-filter>
        </receiver>

        <!-- This is the applicationKey provided by Kiwi -->
        <meta-data android:name="com.movile.kiwi.sdk.applicationKey" android:value="<APPLICATION_KEY>"/>

        <!-- The google backup key -->
        <meta-data android:name="com.google.android.backup.api_key" android:value="<BACKUP_KEY>" />

        <!-- Google Play Services Version metadata -->
        <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />
    </application>
</manifest>

Initialize the Library

You must initialize the library on your application, as following:

KiwiSDK kiwiSDK = KiwiSDKBuilder.create()
                .withContext(this)
                .build();

You must store the KiwiSDK instance to use in your app. You can build a new instance if needed.

Warnings

• Every callback method will run on an isolated thread, other than the thread that initially called the method. For example, when the application calls kiwiSDK.services().discoverCurrentCountry(new MyDiscoverGeolocationListener()); on the main Thread, the onSucess() callback will run on a different Thread, so the application cannot directly perform an UI operation inside it.

What's next

You are now ready to start using kiwi! Next we recommend read the Analytics guide or User guide to learn more about kiwi.