cumtdeyurenjie / curio_android_sdk_gradle

Curio is Turkcell's mobile analytics system, and this is Curio's Android Client SDK library.

Curio Android SDK 1.1.7

Curio is Turkcell's mobile analytics system, and this is Curio's Android Client SDK library. Applications developed for Android 2.3.3 Gingerbread (API Level 10) and higher can easily use Curio mobile analytics with this library.

#What's New Minor bug fix.

#Quick Startup Guide

##Configuration:

All configuration of Curio is made through XML configuration file. For this, create an XML file named curio.xml inside the "res/values" folder of your application project. Sample content of the curio.xml file is as below:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="server_url">https://sampleurl.com/sample/</string>
    <string name="api_key">your api key</string>
    <string name="tracking_code">your tracking code</string>
    <integer name="session_timeout">15</integer>
    <bool name="periodic_dispatch_enabled">false</bool>
    <string name="gcm_senderId">your GCM sender id</string>
	<bool name="auto_push_registration">false</bool>
    <integer name="dispatch_period">5</integer>
    <integer name="max_cached_activity_count">1000</integer>
    <bool name="logging_enabled">false</bool>
</resources>

####Configuration Parameters:

server_url: [Required] Curio server URL, can be obtained from Turkcell.

api_key: [Required] Application specific API key, can be obtained from Turkcell.

tracking_code: [Required] Application specific tracking code, can be obtained from Turkcell.

session_timeout: [Optional] Session timeout in minutes. Default is 30 minutes but it's highly recommended to change this value acording to the nature of your application. Specifiying a correct session timeout value for your application will increase the accuracy of the analytics data.

periodic_dispatch_enabled: [Optional] Periodic dispatch is enabled if true. Default is false.

dispatch_period: [Optional] If periodic dispatch is enabled, this parameter configures dispatching period in minutes. Deafult is 5 minutes. Note: This parameter cannot be greater than session timeout value.

max_cached_activity_count: [Optional] Max. number of user activity that Curio library will remember when device is not connected to the Internet. Default is 1000. Max. value can be 4000.

logging_enabled: [Optional] All of the Curio logs will be disabled if this is false. Default is true.

auto_push_registration [Optional] If true, Curio registers your application for push notifications. But to receive push notifications, application should contain required configuration parameters in AndroidManifest.xml and implement required receiver/service classes. For more information please read Google's documentation about GCM

gcm_senderId [Required] GCM Sender Id parameter, can be obtained from Turkcell. Required if auto push registration is enabled otherwise no need to specify.

##Integration with Android Studio Projects Integration with Android Gradle projects is in two steps;

1-Add jitpack repo URL into root build.gradle file as below:

repositories {
    maven {
        url "https://jitpack.io"
    }
}

2-Add Curio's dependency into app's build.gradle file (change version with the latest):

dependencies {
   	compile 'com.github.Turkcell:Curio_android_SDK_Gradle:1.0.8'
}

##Integration with Eclipse Projects You can still use .jar library version of Curio SDK with your Eclipse projects. You can always download the newest version of the curiosdk.jar from here

##Dependencies: Curio SDK uses Google Ad Id, and GCM so its dependent to Google Play Services. You should add Play Services library dependencey to your application project.

##Usage:

###Instance Creation and Starting Session: Instance creation and session start should be in onCreate() method of application's main (or enterance) activity class.

protected void onCreate(Bundle savedInstanceState) {
	...
	CurioClient.getInstance(context).startSession();
	...
}

###Starting Screen:

Should be called once per activity class or fragment.

protected void onStart() {
	CurioClient.getInstance(context).startScreen(SampleActivity.this, "Sample Activity", "sample");
	...
}

###Ending Screen: Should be called once per activity class or fragment.

protected void onStop() {
	CurioClient.getInstance(context).endScreen(SampleActivity.this);
	...
}

###Sending Event: ... CurioClient.getInstance(context).sendEvent("sample event key", "sample event value"); ...

###Ending a Timed Event: You can send a timed event's duration to Curio server by calling this method. Developers are responsible for measuring/calculating durations of events and passing them as duration parameter of the endEvent method as below. Durations should be in miliseconds. You should first call sendEvent at the start of the event, and then call endEvent at the end of the event with calculated duration parameter. endEvent method should be called with the same key-value pair of corresponding sendEvent method, that's important.

...
CurioClient.getInstance(context).endEvent("sample event key", "sample event value", 35045);
...

You can also send categorized event keys using ">" sign in the key string. Such as "Cat1>Cat2>Cat3".

###Ending Session: Session ending should be in onStop() method of application's main (or exit) activity class, and also it should be checked if application is actually finishing or just going to another activity with isFinishing() method. This check should be made on main (or exit) activity class.

protected void onStop() {
	...
	if(isFinishing()){
		CurioClient.getInstance(context).endSession();
	}
	...
}

###Sending Push Notification Data (if auto push registration is enabled): For sending received push notification data to Curio push server, getPushData(Intent) method should be called. This method should be called before startSession() method as below:

protected void onCreate(Bundle savedInstanceState) {
	...
	//If your application receives push notification. Optional
	CurioClient.getInstance(context).getPushData(getIntent());
	
	//Start session
	CurioClient.getInstance(context).startSession();
	...
}

###Sending Custom Id (if auto push registration is enabled): For sending custom id to Curio server, setCustomId(String) or sendCustomId(String) method should be called. If setCustomId(String) method is used than it should be called before startSession() method as below:

protected void onCreate(Bundle savedInstanceState) {
	...
	//If your application receives push notification. Optional
	CurioClient.getInstance(context).getPushData(getIntent());
	
	//Custom id. Optional.
	CurioClient.getInstance(context).setCustomId("sampleCustomId");
	
	//Start session
	CurioClient.getInstance(context).startSession();
	...
}

or you can call sendCustomId(String) method any time in your app after you call startSession() as below:

...
CurioClient.getInstance(context).sendCustomId("sampleCustomId");
...

Note: You should use the newer version of sendCustomId method which has the listener parameter:

void sendCustomId(String customId, ICustomIdRegisterListener customIdRegisterListener);

###Unregistering from Push Notification Server (if auto push registration is enabled): You can call unregisterFromNotificationServer() method from you app to unregister your app from Curio Push notification server. After calling this method as below, your app will not receive push notifications:

...
CurioClient.getInstance(context).unregisterFromNotificationServer();
...

Actually that's all you need to do in your application for a quick and simple integration. For more detail, please keep reading next sections.

Note: You should use the newer version of unregisterFromNotificationServer method which has the listener parameter:

void unregisterFromNotificationServer(IUnregisterListener unregisterListener);

###User Tagging:

Your applications can set tags for individual users, and query already set tags.

For sending tags:

void sendUserTags(final Map<String, String> userTagValueMap, final IUserTagsResponseListener userTagsResponseListener)

For querying tags:

void getUserTags(IUserTagsResponseListener userTagsResponseListener)

#API and Usage Details ##Initialization

###Starting Session By starting session, you tell Curio server that application is launched, so before doing anything else you should start a session at the very beginning of the application by calling:

protected void onCreate(Bundle savedInstanceState) {
	...
	CurioClient.getInstance(context).startSession();
	...
}

once in onCreate method of the main (or enterance) activity. A session will be closed by the server if no request sent for a time period defined by session_timeout parameter in curio.xml. After the session has timed out, your requests will get HTTP 401 unauthorized response from server and SDK will start a new session automatically for you and then send the request with new session code.

Important: If your application supports multiple orientations, Android OS may call onCreate() of your activities after a device orientation change depending on your application's AndroidManifest.xml configuration. Developers are responsible for handling session start calls on orientation changes. If onCreate() method is called on each device orientation change, application should detect it and should not call startSession() more than once per application launch. If this should not handled properly, application will produce wrong analytics data.

Methods:

public void startSession()

public void startSession(final boolean generate)

Parameters:

generate: If this parameter is true, method forces to generate a new session code.

###Starting Screen By starting session, you tell Curio server that a new Activity (application screen) is displayed by user. So you should start a new screen in onStart() method of each activity that you'd like to track by calling:

protected void onStart() {
	CurioClient.getInstance(context).startScreen(SampleActivity.this, "Sample Activity", "sample");
	...
}

Methods:

public void startScreen(Context context, String title, String path)

public void startScreen(final String className, final String title, final String path)

Parameters:

context or className: This parameter is used as a key for the screen and thus it should be unique for every screen (means an activity, service or fragment). If using in a class that's not unique for each screen (such as fragments), String className parameter can be used instead of Activity instance. But do not forget each className parameter should be unique for each screen.

protected void onStart() {
	CurioClient.getInstance(context).startScreen("sample_Fragment_1", "Sample Activity", "sample");
	...
}

title: Screen title, unique for the screen.

path Screen path, unique for the screen. ###Ending Screen By ending session, you tell Curio server that the current Activity is finished by user. So you should call endScreen() method in onStop() method of each activity that you start tracking by calling startScreen(). You can end a screen by calling:

protected void onStart() {
	CurioClient.getInstance(context).endScreen(SampleActivity.this);
	...
}

Please note that Android API Level 11 (Honeycomb) or higher OS's always call onStop() method of Activities or Fragments when leaving that Activity. So it's safe to use onStop() method for screen ending on API Level 11 or higher. But prior to Honeycomb, Activities can be killed before OS calls onStop(), so according to the nature of your application you can use onPause() method instead of onStop() if your application runs on an Android version prior to Honeycomb.

Methods:

public void endScreen(Context context)

public void endScreen(final String className)

Parameters:

context or className: This parameter is used as a key for the screen and thus it should be unique for every screen (means an activity, service or fragment). If using in a class that's not unique for each screen (such as fragments), String className parameter can be used instead of Activity instance. But do not forget each className parameter should be unique for each screen.

protected void onStart() {
	CurioClient.getInstance(context).startScreen("sample_Fragment_1");
	...
}

###Sending Event You can track certain user actions like button clicks, user choices, etc. by sending custom events to Curio. You can send events by calling:

...
CurioClient.getInstance(context).sendEvent("sample event key", "sample event value");
...

Methods:

public void sendEvent(String eventKey, String eventValue)

Parameters:

eventKey: This parameter is used as a key for the custom event or event group. Sample: "button_click"

eventValue: This parameter is used as a value for the custom event. Sample: "login_button" ###Ending Session By ending session, you tell Curio server that user has quit from the application. Session ending should be in onStop() method of application's main (or exit) activity class, and also it should be checked if application is actually finishing or just going to another activity with isFinishing() method.

protected void onStop() {
	...
	if(isFinishing()){
		CurioClient.getInstance(context).endSession();
	}
	...
}

Methods:

public void endSession()

##Periodic Dispatch and Offline Cache To save bandwith and batterly life of device, Curio client SDK can dispatch requests periodically instead of sending every request real-time. When periodic dispatch is enabled from curio.xml configuration file, only session start and session end requests are delivered real-time, other requests are delivered automatically each time when dispatch period is over. You can configure dispatch period from configuration XML.

Also Curio client SDK has an internal cache for storing analitics data when device is offline. This offline data cache is enabled automatically when device network connectivity is not available. In same way, stored offline analytics data is sent to server automatically when device goes online again. You can configure the capacity of this offline cache from configuration XML.