# [Table of Contents](#table-of-contents)
*Note the sections 1,2,3, 4 are applicable for both wappier solutions*
1. [Overview](#overview)
2. [Set Up in 3 Steps!](#set-up-in-3-steps)
	1. [Import Libraries](#import-libraries)
	2. [Update Android Manifest](#update-android-manifest)
	3. [Initialize SDK](#initialize-sdk)
3. [Tracking Events](#tracking-events)
	1. [Tracking Custom In-App Actions](#tracking-custom-actions)
	2. [Tracking Purchase Events](#tracking-purchase-events)
4. [Tracking User Profile Details](#tracking-userDetails)
	1. [Tracking User Profile attributes](#tracking-userProfileAttributes)
	2. [Adding or Removing tags to a User](#tracking-tags)
	3. [Adding or Removing Key-Value pairs to a User](#tracking-kvp)
	4. [Getting Control/Target Group Status](#tracking-controlTargetGroupStatus)
5. [Loyalty Icon & Profile Customization](#loyalty-icon-profile-customization)
*Note: this section is applicable for  Loyalty & Retention solution*
	1. [Loyalty Icon Set up and Position](#loyalty-icon-set-up-and-position)
	2. [Showing Loyalty User Profile](#showing-loyalty-user-profile)
	3. [Loyalty Profile Orientation](#loyalty-profile-orientation)
	4. [Setting a username for the user](#setting-up-username-for-user)

6. [In-app Products Setup & Redemption Flow](#in-app-products-setup-redemption-flow)
*Note: this section is applicable for  Loyalty & Retention solution*

7. [Regional Pricing using Control Group](#regional-pricing-using-control-group)
*Note: this section is applicable for  Regional Pricing  solution*




## **OVERVIEW** (for both wappier solutions)<a name="overview"></a>

The **wappier Loyalty SDK** consists of a core library which enables tracking of in-game actions.

Here's how it works:

* Events are recorded each time an action is performed (e.g. the *INAPP_ACTION* event), every time the user launches the game (e.g. the *OPEN* event) and the first time the game runs on the user’s device (e.g. the *FIRST_RUN* event).

* Then, they are processed in real time by wappier’s **Revenue Management Platform** and **Machine Learning Technology** in order for the user to be rewarded with the corresponding reward.

Here are some of the events required to be tracked from your game and used by wappier’s Machine Learning Technology to optimize Loyalty’s performance in your game:

|**Event Name**|**Type**|**Recorded when**|
|---|---|---|
|FIRST_RUN|Unique|User installs the game for the first time|
|OPEN|Repetitive|User launches the game|
|TIME_SPENT|Repetitive|User exits from the game
|PURCHASE|Repetitive|User buys an in-app product
|CUSTOM_EVENT_NAME|Unique or Repetitive|Depending on the game, a variety of actions can be tracked and incentivized.  Some event examples: *TUTORIAL_COMPLETE, LEVEL_COMPLETE, HIGHSCORE, HERO_LEVEL_5*

![Image URL not working properly](https://s3.amazonaws.com/wizzogames-live/marketing_content/kb_wappiermachine.png)
*How user data are tracked and processed real time by wappier’s Revenue Management Platform and Machine Learning Technology in order for the user to be rewarded with a Personalized Rewarding Loyalty Scheme.*

**Requirements before Set Up**
We will provide you with an API key that you’ll need to add in your game during the integration in order for the SDK to communicate with our Revenue Management Platform.

The **wappier Optimization SDK** needs *Android SDK 16 (4.1)* or later versions to work properly.


## **SET UP IN 3 STEPS!** (for both wappier solutions)<a name="set-up-in-3-steps"></a>

Below you will find the required steps to integrate the **wappier Optimization SDK** with your game:

#### **Step 1 – Import Libraries**<a name="import-libraries"></a>

For **wappier Libraries**, copy *WappierSDK-x.y.z-liveRelease.aar* file at the libs folder and add it to project build path.

If *ProGuard* is enabled, the following rules should be added to ProGuard rules:
```
-keep public class com.wappier.** { *; }
```

For **Google Libraries**, add the following dependency to app/build.gradle file:
```gradle
compile 'com.google.android.gms:play-services-basement:12.0.1'
```

Please note that the minimum version of Google Play base library that is supported by the **wappier Optimization SDK** is version 9.8.1 and the maximum one is 12.0.1. If you need to include another base version, please add the below dependency instead:
```gradle
compile 'com.google.android.gms:play-services-ads:15.0.1'
```

Additional dependencies:
```gradle
compile 'com.android.support.constraint:constraint-layout:1.1.0'
compile 'com.android.support:design:X+'
compile 'com.android.support:cardview-v7:X+'
compile 'com.android.support:recyclerview-v7:X+'
```
where X is the compileSDKVersion that the game supports.

#### **Step 2 – Update AndroidManifest.xml**<a name="update-android-manifest"></a>
Add the following declaration to the *AndroidManifest.xml* inside the tag for debugging purposes:
```xml
<meta-data android:name="wappier_debug" android:value="true"/>
```
The wappier_debug boolean value enables logging messages.

Add the following permissions to the *AndroidManifest.xml*:
```java
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> // this permission is optional
```

The **wappier Optimization SDK** is using the *android.permission.ACCESS_FINE_LOCATION* permission to determine the device location in order to serve region-specific content and features accurately.

For this reason, apps targeting Android Marshmallow (API 23) and later should prompt users to grant it at runtime instead of install time. Since users can revoke permissions at any time from the app Settings screen, your app needs to check that it has the permissions it needs every time it runs. For more details on how to achieve this, please follow [this link](https://developer.android.com/training/permissions/index.html).

If you do not handle *android.permission.ACCESS_FINE_LOCATION* permission for API > 23, SDK should be functional but location would not be accurate.


#### **Step 3 – Initialize SDK**<a name="initialize-sdk"></a>
To initiate the **wappier Optimization SDK**, create a new Application class or update the existing one and add the following line at the *onCreate()* method of that class:
```java
Wappier.getInstance()
		.startSession(this,YOUR_APPLICATION_KEY)
		.setUserName(your_unique_user_identifier);
```

## **Tracking Events** (for both wappier solutions)<a name="tracking-events"></a>
The steps below provide instructions for tracking in-game events. FIRST_RUN, OPEN and TIME_SPENT events are tracked automatically.

#### **Tracking Custom In-App Actions**<a name="tracking-custom-actions"></a>
The steps below provide instructions for tracking in-game events. FIRST_RUN, OPEN and TIME_SPENT events are tracked automatically.

#### **Tracking Custom In-App Actions**
To track in-game actions add the following line:
```java
Wappier.getInstance().trackAction("YOUR_CUSTOM_EVENT_NAME");
```

YOUR\_CUSTOM\_EVENT\_NAME can have any custom value including the following special characters:
*0-9, A-Z, a-z, \# $ % = @ ! { } ( ) \[ ] < > \` ~ & ? . : ; \_ | ^ + \- *

These actions are directly correlated with the gameplay style of each game and they are the main source of points for the user. Here you may find some common examples of tracked actions:

|Event Name|Occurrence|Tracked when|
|---|---|
|TUTORIAL_COMPLETE|Unique|User finishes the last objective of the tutorial flow|
|LEVEL_COMPLETE|Repetitive|User completes a level or stage in the game|
|BATTLE_WON|Repetitive|Win a match versus A.I.|
|HIGHSCORE|Repetitive|User completes an already finished level or stage with higher score|
|ACHIEVEMENT|Repetitive|User earns an in-game achievement|
|HERO_LVL_5|Unique|Hero reached level 5|
|CASTLE_LVL_7|Unique|Main building was upgraded to level 7|
|FIRST_PURCHASE|Unique|User completes his first transaction|
|50_ONLINE_BATTLES|Unique|Win 50 battles versus real opponents|

#### **Tracking Purchase Events**<a name="tracking-purchase-events"></a>
In order to track in-app purchases performed in your game, add the following line:
```
Wappier.getInstance().trackPurchase(
	revenue,
	"currencyCode",
	"googleOrderId",
	"productId",
	"purchaseToken"
	);
```

Mandatory Fields:

|Value|Type|Description|Example|
|---|---|---|---|
|revenue|Double|Total numeric amount for the purchase|19.99|
|"currencyCode"|Char|The local currency code of the transaction|SAR|
|"googleOrderId"|Char|The GPA-formatted order ID of the transaction|GPA-1234.1234.1234.12345|
|"productId"|Char|The product identifier of the in app product|diamonds.king.001|
|"purchaseToken"|Char|A token that uniquely identifies a purchase for a given item and user pair|This alphanumeric string is 150-200 characters long|

The following code snippet suggests a way to track a purchase event:
```
// Callback for when a purchase is finished
IabHelper.OnIabPurchaseFinishedListener mPurchaseFinishedListener = new IabHelper.OnIabPurchaseFinishedListener() {
	if (purchase.getSku().equals(..SKU id..)) {
		Wappier.getInstance().trackPurchase(
			1.80,
			"EUR",
			purchase.getOrderId(),
			purchase.getSku(),
			purchase.getToken()
			);
	}
};
```

## **TRACKING USER DETAILS** (for both wappier solutions)<a name="tracking-userDetails"></a>

#### **Tracking User Profile attributes** <a name="tracking-userProfileAttributes"></a>

To track user profile attributes add the following code:

```java
HashMap<String, String> attributesMap = new HashMap<>();
attributesMap.put("userAvatarURL", "avatar.jpeg");
attributesMap.put("profileName","Bob");
attributesMap.put("email", "bob@mail.com");
attributesMap.put("phoneNumber", "555-3982");
attributesMap.put("country", "US");
Wappier.getInstance().trackUserProfile(attributesMap);
```
You can use any number of attribute keys and values. User Profile attributes will be associated with the user document.

#### **Adding or Removing tags to a User** <a name="tracking-tags"></a>

To add or remove tags to a user, add the following code:
```java
Wappier.getInstance().addTag("addTag");
```
```java
Wappier.getInstance().removeTag("removeTag");
```
You can use any string as a tag. Tags are associated with the user document and can be used for segmentation, targeting and analytics.

#### **Adding or Removing Key-Value pairs to a User** <a name="tracking-kvp"></a>

To add or remove one or multiple Key-Value pair(s) to a user add the following code:

```java
 Wappier.getInstance().trackKVP("KvpKey","KvpValue");
```

```java
 HashMap<String, String> KvpHash=new HashMap<>();
                KvpHash.put("key1","kvpValue1");
                KvpHash.put("key2","kvpValue2");
                KvpHash.put("key3","kvpValue3");
                Wappier.getInstance().trackKVP(KvpHash);
```


#### **Getting Control/Target Group Status** <a name="tracking-controlTargetGroupStatus"></a>
```java
boolean controlGroupFlag = Wappier.getInstance().isUserInControlGroup();
```


## **LOYALTY ICON & PROFILE CUSTOMIZATION**  (for Loyalty & Retention solution)<a name="loyalty-icon-profile-customization"></a>
The below options can be used to handle the Loyalty Icon and User Profile in your game.

#### **Loyalty Icon Set up and Position**<a name="loyalty-icon-set-up-and-position"></a>
You can add the Loyalty Icon programmatically or with xml in your layout. When the user taps on this icon, his Loyalty Profile card is shown.
```
// Programmatically
WappierButton mCustomButton= new WappierButton();

// Xml
<wappier.sdk.wappier.com.loyalty.ui.WappierButton
android:id=”@+id/wappier_button”
android:layout_width=”50dp”
android:layout_height=”50dp”
android:layout_alignParentBottom=”true”
android:layout_alignParentEnd=”true”
android:layout_alignParentRight=”true” />
```

To present or hide the Loyalty Icon at any given time, use one of the following lines:
```
mCustomButton.showLoyIcon("REFERRER");
```
```
mCustomButton.hideLoyIcon();
```
where "REFERRER" is a free text parameter describing the screen that the Icon has shown.

To set the Loyalty Icon position at any given in-game screen, use one of the following lines:
```
mCustomButtom.setPosition(200,200) // setPosition(xPoint,yPoint)
```
```
mCustomButton.setPosition(Position.Top,Position.Left)
```
```
mCustomButton.setPosition(10,Position.Top,Position.Left)
```

One of the below constants can also be used in order to set the Loyalty Icon position:

|Constant|Position|
|---|---|
|Position.DEFAULT||Icon displays default position|
|Position.LEFT||Icon displays at left of the screen|
|Position.Right|Icon displays at right of the scree|
|Position.Top|Icon displays at top of the screen|
|Position.Bottom|Icon displays at bottom of the screen|

#### **Showing Loyalty User Profile**<a name="showing-loyalty-user-profile"></a>
To present the Loyalty User Profile manually without him tapping on the Loyalty Icon, add the following line:
```
mCustomButton.showLoy();
```

#### **Loyalty Profile Orientation**<a name="loyalty-profile-orientation"></a>
You can control the orientation of the Loyalty Profile depending on the orientation that your game supports:
```
Wappier.getInstance()
.startSession(this, Env.APP_KEY)
.setLOYOrientation(PREFERRED_ORIENTATION);
```
"PREFERRED\_ORIENTATION" can take one of the following constants:

|Constant|Result|
|---|---|
|Orientation.PORTRAIT|Lock orientation to portrait|
|Orientation.LANDSCAPE|Lock orientation to landscape|
|Orientation.OPEN|Loyalty card will rotate depending on device orientation|

#### **Setting a username for the user**<a name="setting-up-username-for-user"></a>
You can link multiple devices to a single account by setting the username on session start request.
```
Wappier.getInstance()
.startSession(this, Env.APP_KEY)
.setUserName(your_unique_user_identifier);
```


## **IN-APP PRODUCTS SETUP & REDEMPTION FLOW** (for Loyalty & Retention solution)<a name="in-app-products-setup-redemption-flow"></a>
In order to include your in-app products in the Loyalty Reward Scheme, each of the items have to be matched with a unique, custom name. When the user tries to spend points to redeem an item, the SDK should be informed if that redemption is successful in order to subtract the respective points from the user's Loyalty Profile.

To receive redemption notifications, use one of the following code snippets in your activity:
```
Wappier.registerRedeemCallback(new RedeemListener() {
	@Override
	public void redeemCallback(String sku, final String redemptionId, int quantity) {
	}
});
```
```
RedeemListener redeemListener = new RedeemListener() {
	@Override
	public void redeemCallback(final String sku, final String redemptionId, final int quantity) {
		final Handler handler = new Handler();
		handler.postDelayed(new Runnable() {
			@Override
			public void run() {
				if (sku.equals("SKU1") || sku.contains("test_sku_")) {
					.......
				}
			}
		}, 3000);
	}
};


    @Override
    protected void onStart() {
        super.onStart();
        Wappier.getInstance().registerRedeemCallback(redeemListener);
    }

    @Override
    protected void onStop() {
        super.onStop();
        Wappier.getInstance().unregisterRedeemCallBack();
    }

```

When the transaction is completed and the user receives the reward you can call the following line to complete the redemption flow:
```
// In case of success
Wappier.getInstance().redemptionIsCompleted(true, redemptionId);

// In case of error
Wappier.getInstance().redemptionIsCompleted(false, redemptionId);
```

***Note: If we do not receive any of the above callbacks within 7 seconds, we’re going to treat this redemption as a failed one.***

You can refer to the following example, please don’t forget to call *redemptionIsCompleted* method as soon as possible:
```
Wappier.registerRedeemCallback(new RedeemListener() {
	@Override
	public void redeemCallback(String sku, final String redemptionId, final int quantity) {
		// added delay to emulate a transaction
		final Handler handler = new Handler();
		handler.postDelayed(new Runnable() {
			@Override
			public void run() {
				if (sku.equals("test_sku_1") || sku.contains("test_sku_1")) {
					Wappier.getInstance().redemptionIsCompleted(true, redemptionId);
				}
				else {
					Wappier.getInstance().redemptionIsCompleted(false, redemptionId);
				}
			}
		}, 3000);
	}
});
```

**Possible responses:**
```
// Failed redemption due to a missing item ID
Error buffer(com.android.okhttp.internal.http.Http1xStream$FixedLengthSource@8a15e97).inputStream() Message :{"error": "Reward is not found, is locked or claimed","code":916} Code :400
```
```
// Failed redemption due to a game error
Redeem sending demo.sku.com with Quantity : 5 to server
Redeem Item found. 5000 will committed
Calling mother app callback with SKU : demo.sku.com
Redemption is Completed :false
Redeem – Status: 1000
Points restored
```
```
// Successful redemption
Redeem sending demo.sku.com with Quantity : 5 to server
Redeem Item found. 5000 will committed
Calling mother app callback with SKU : demo.sku.com
Redemption is Completed :true
Redeem – Status: 200
Transaction Completed
```



## **Regional Pricing using Control Group** (for Regional Pricing solution)<a name="regional-pricing-using-control-group"></a>
You can enable dynamic pricing service via the wappier dashboard by assigning prices to your in app products. The new prices will be visible to a predefined percentage of the population while the rest of it will belong to a control group that will be used to compare performance.
Users belonging in the control group will notice no differences in price points.

You normally send an SKU ID to Google's In App Billing API according to the guidelines described here. By using our pricing optimization service, the SKU is no longer a predefined constant but can rather change whenever the application launches.

For this reason, you have to fetch the assigned SKU based on the original SKU by using the below method (at the start of your activity and after the SDK has been initialized):

```
Wappier.getInstance().getSku(String originalSku);
```

For example, if you have an SKU named *'com.company.magic_sword'*, you should retrieve the name of the dynamically allocated equivalent of that SKU:

```
String regionalSku;
public class MainActivity extends Activity {
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		regionalSku = Wappier.getInstance().getSku("com.company.magic_sword");
		//Now you can use the regionalSku in Google billing API related methods
	}
}
```

In case of a failure (network issue or expired pricing test), methods returns the original SKU.

## **PROPRIETARY NOTICE**
This document and any files transmitted with it are confidential and intended solely for the use of the individual or entity to whom they are addressed. This message contains confidential information and is intended only for the individual or entity named. If you are not the named addressee you should not disseminate, distribute or copy this document.

If you are not the intended recipient you are notified that disclosing, copying, distributing or taking any action in reliance on the contents of this information is strictly prohibited.

The information contained in these documents is confidential, privileged and only for the information of the intended recipient and may not be used, published or redistributed without the prior written consent of wappier Ltd.