Curio Android SDK

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

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 at the right side:



    <?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. Default 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.




Dependencies

Curio SDK uses Google Ad Id, so its dependent to Google Play Services. You should add Play Services library project to your application project.

You can learn more detail on how to integrate your application project with Play Services here on Google's documentation.

Also you should edit project.properties file to point correct path to Play Services library project:




    android.library.reference.1=path/to/playservices/project/google-play-services_lib


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 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 at the right side:



    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 at the right side:



    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 at the right side:



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

                                

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 at the right side, your app will not receive push notifications:

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.



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

                                

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:

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.




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

                                

Methods:



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



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

                                

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:

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.



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

                            

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.



Curio iOS SDK

Curio is Turkcell's mobile analytics system, and this is Curio's Client iOS library. Applications developed for iOS 6.0+ can easily use Curio mobile analytics with this library.

Quick Startup Guide

You can drag'n drop Curio project file into your project. Additionally you should add the dependencies.


Dependencies

You should Click on Targets -> Your App Name -> and then the 'Build Phases' tab.

And expand 'Link Binary With Library' and click + sign to add required framework if they are not available.

If you don't want to run automated unit tests, then you should remove CurioSDKTests.m, CurioSettingsTest.m and CurioDBTests.m files from compilation by Click on Targets -> Your App Name -> And then the 'Build Phases' tab and expand Compile Sources to remove them by clicking on - sign while mentioned source files selected.



    - Foundation.framework
    - UIKit.framework
    - CoreTelephony.framework
    - libsqlite3.dylib
    - CoreLocation.framework

                                

Configuration

There are two ways to configure CurioSDK.


Info.plist Configuration

You can just copy'n paste CurioSDK item within sample project's Info.plist or CurioSDKTests-Info.plist contained in CurioSDK.Core tests to your project's Info.plist file and edit parameters as you wish.

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

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

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

SessionTimeout: [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.

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

DispatchPeriod: [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.

MaxCachedActivityCount: [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.

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

LogLevel: [Optional] Contains level of the print-out logs. 0 - Error, 1 - Warning, 2 - Info, 3 - Debug. Default is 0 (Error).

RegisterForRemoteNotifications: If enabled, then Curio SDK will automatically register for remote notifications for types defined in "NotificationTypes" parameter.

NotificationTypes: Notification types to register; available values: Sound, Badge, Alert

FetchLocationEnabled: [Optional] If enabled, the current location of the device will be tracked while using the application. Default is true. The accuracy of recent location is validated using MaxValidLocationTimeInterval. Location tracking stops when the accurate location is found according to the needs. For further location tracking you can use [[CurioSDK shared] sendLocation] method. In order to track locations in iOS8 NSLocationWhenInUseUsageDescription must be implemented in Info.plist file.

MaxValidLocationTimeInterval: [Optional] Default is 600 seconds. The accuracy of recent location is validated using this parameter. Location tracking continues until it reaches to a valid location time interval.



Manual Configuration

You can specify CurioSDK parameters whenever you want to start a session on client by invoking startSession function just like the code at the right side.


 [[CurioSDK shared] startSession:@"server_url"
    apiKey:@"XXXXX"
    trackingCode:@"XXXXX"
    sessionTimeout:4
    periodicDispatchEnabled:YES
    dispatchPeriod:1
    maxCachedActivitiyCount:1000
    loggingEnabled:YES
    logLevel:0
    registerForRemoteNotifications:YES
    notificationTypes:@"Sound,Badge,Alert"
    fetchLocationEnabled:YES
    maxValidLocationTimeInterval:600
    appLaunchOptions:launchOptions
    ];


                                

Usage


Starting a Session

You can start a session whenever application starts-up by invoking startSession function within CurioSDK class.


    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[CurioSDK shared] startSession:launchOptions];
    ...
    }

                                

Starting a Screen

You can start a screen by invoking startScreen function within CurioSDK class.



    - (void) viewDidAppear:(BOOL)animated {
    [[CurioSDK shared] startScreen:[self class] title:@"Master view" path:@"Master-view"];
    }


                                

Ending a Screen

You can end a screen by invoking startScreen function within CurioSDK class.



    - (void) viewDidDisappear:(BOOL)animated {
    [[CurioSDK shared] endScreen:[self class]];
    }

                                

Sending an Event

You can send event-key and value pairs by invoking sendEvent function within CurioSDK class.



    - (IBAction)sendEvent:(id)sender {
    [[CurioSDK shared] sendEvent:@"Clicked button" eventValue:NSStringFromClass([self class])];
    }


                                

Ending a Session

You can end started session by invoking endSession function with CurioSDK class. Normally there is no need to manually end application session. CurioSDK automatically handles session-finish processes to notify Curio Server.



    - (void)applicationWillTerminate:(UIApplication *)application {
    // Called when the application is about to terminate. Save data if appropriate. See also
    applicationDidEnterBackground:.

    [[CurioSDK shared] endSession];
    }


                                

Registering for push notifications

Curio iOS SDK can register your application for remote push notifications automatically if you set "RegisterForRemoteNotifications" parameter true and set "NotificationTypes" parameter. You also have to implement "didReceiveRemoteNotification" and "didRegisterForRemoteNotificationsWithDeviceToken" methods as shown at the right side:



    - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
    [[CurioNotificationManager shared] didReceiveNotification:userInfo];
    }

    //or if you implement this method
    - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo
    fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    completionHandler(UIBackgroundFetchResultNewData);
    [[CurioNotificationManager shared] didReceiveNotification:userInfo];
    }

    - (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData
    *)deviceToken {
    [[CurioNotificationManager shared] didRegisteredForNotifications:deviceToken];
    }


                                

Fetch and Send Location

You can track device location using the method at the right side. Please check if the FetchLocationEnabled is YES before using this method. In order to track locations in iOS8 NSLocationWhenInUseUsageDescription must be implemented in Info.plist file.



    [[CurioSDK shared] sendLocation];

                                

Get Notification History

You can get notification history of push notifications which have been sent to device.



    [[CurioSDK shared] getNotificationHistoryWithPageStart:0 rows:5 success:^(NSDictionary *responseObject) {
    NSLog(@"%@", responseObject.description);
    } failure:^(NSError *error) {
    NSLog(@"%@", error.description);
    }];

                                

Sending Custom Id (if auto push registration is enabled):

For sending custom id to Curio server, sendCustomId method should be called as at the right side:



    ...
    [[CurioSDK shared] sendCustomId: @"sample custom id"];
    ...

                                

Unregistering from Push Notification Server (if auto push registration is enabled):

You can call unregisterFromNotificationServer method from your app to unregister your app from Curio Push notification server. After calling this method as at the right side, your app will not receive push notifications:



    ...
    [[CurioSDK shared] unregisterFromNotificationServer];
    ...

                                

Internals


Curio SDK consists of two different workflows which maintains storage and submission functionalities.

First workflow (which we will call storage workflow) handles database records one way to save user actions to local storage (SQLITE). All storage functions are located in CurioDBToolkit.m and CurioDB.m. When a user hooks up a function related to SDK, first of all CurioSDK stores it to local storage no matter we are online or not or have periodic dispatch requests (PDR) enabled or not.

For those requests CurioDBToolkit::addAction function runs to insert created action record to db. All actions converts to CurioAction.m object and stores and retrieves by serializating to CurioAction.

CurioAction object stored into SQLITE table named ACTIONS which is created on first run within CurioDB.m

Second workflow (which we will call submittance workflow) handles retrieval of records and transmittance to server side over internet. Main core functionality of this workflow runs on CurioPostOffice.m module.

PIt starts to run in two way... one is periodically -if PDR is enabled- and other one is synchronized -if PDR is disabled-. Synchronized run has nothing to do with thread synchronization but running parallel with user actions.

If PDR is enabled there is a sleeping thread runs in CurioPostoffice::opQueue queue and wakes up every dispatch period (which can be configured within settings) and runs CurioPostoffice::tryToPostAwaitingActions function to try to post actions stored in database. If PDR is not enabled, there is an internal notification name which is stored in CS_NOTIF_NEW_ACTION value globally which waits for any user action signal to run CurioPostoffice::tryToPostAwaitingActions.

Most critical point in submittance workflow is localted within CurioPostoffice::tryToPostAwaitingActions function which handles mostly every conversions and transfers.

It requires to run in background thread if otherwise is not specified with canRunOnMainThread parameter. If it is not, it switches itself back to a background thread to not to intercept any user comfort. It checks whether device is online or not. If it is not, it switches awaiting records into offline records, otherwise tries to post actions ordered by action time which is saved in aId column.

It puts action objects into two arrays (if PDR is disabled just uses one array) to collect them in batch manner. First one is offlineActions and second one is pdrActions array. Main functionality within CurioPostoffice::tryToPostAwaitingActions is to iterate through records and collect them as PDR -if enabled- or Offline otherwise if they are online records then sending them to server immediately and in other cases pushing collected arrays to server as soon as they are finished.

Other than two main workflows, there is a CurioNetwork.h which handles network status changes and notifies with notification calls to all around the SDK.


    +--------+       +--------------+
    |        |       |              |
    | Curio  |       | User Actions |
    | Server |       |              |
    |        |       +------+-------+
    +---^----+              |
    |   SYNC              ASYNC
    |                       |
    +---+----+              |
    |  Post  |         +----v----+
    | Office |         |DBToolkit|
    +---^----+         +----+----+
    |                       |
    |                       |
    ASYNC               ASYNC
    |        POOL           |
    |    +---------+        |
    |    |  Local  |        |
    +----> Storage <----+---|
    +---------+

                    

Turkcell Curio Web SDK

Turkcell Curio ile kullanıcılarınızın web sitenizdeki hareketlerini gözlemleyebilirsiniz.

Sitenize ekleyin


  • https://gui-curio.turkcell.com.tr adresinden uygulamanızı oluşturun.
  • Aşagıdaki kodu web sayfanıza ekleyiniz.
  • Oluşturdugunuz uygulamanın TRACKING_CODE ve API_KEY değerlerini yandaki koda yerleştirin.


    <script src="https://curio.turkcell.com.tr/api/js/curio-2.0.0.js"></script>
    <script type='text/javascript'>
    Curio.init("API_KEY", "TRACKING_CODE");
    </script>


Kullanımı

Kullanıcıların hareketlerini gözlemlemek için kaydetmek istediğiniz kullanıcı etkileşimlerini Turkcell Curio'ya göndermelisiniz.
Yukarıdaki kodu sitenize ekledikten sonra, bu kodun size sağladığı API ile Turkcell Curio'ya bilgi gönderimi yapabilirsiniz.
Bu bilgiler yeni bir sayfa açılması, web sitenizdeki bir elemente tıklanması veya bulunulan sayfanın terk edilmesi gibi hareketleri içerebilir.



API

Turkcell Curio'yu size sağlanan 5 adet fonksiyon ile kullanabilirsiniz.

  • Yeni Ziyaret (New Visit)
  • Yeni Sayfa (New Hit)
  • Yeni Etkileşim (New Event)
  • Sayfa Çıkış (End Hit)
  • Ziyareti Bitir (End Visit)


Yeni Ziyaret (New Visit)

Curio için sayfanıza eklediğiniz JavaScript kodu (Curio.init) ile yeni ziyaret yaratılacaktır. Sizin yeni bir ziyaret yaratmak için herhangi bir şey yapmanıza gerek yoktur.

Yeni ziyaret yaratıldıktan sonra sunucudan gelen gelen parametreler kendiliğinden Curio.clientData nesnesine yazılacaktır. Sizin response ile ilgili bir şey yapmanıza gerek yoktur. Sunucu hatası, bağlantı hatası vb. sebeplerden ötürü yeni ziyaret yaratılamadığı zaman Curio'ya yapılacak her istek öncesi yeni ziyaret oluşturma denemesi yapılacaktır.



Yeni Sayfa (New Hit)

Zorunlu Parametreler

  • pageTitle
  • path


Örnek Kullanım

Curio.hitCreate() fonksiyonunu kullanarak çağırım yapabilirsiniz.


    Curio.hitCreate({pageTitle: "Page Title", path: "Page URL"});

                                

Yeni Etkileşim (New Event)

Zorunlu Parametreler

  • eventKey
  • eventValue


Örnek Kullanım

Curio.eventCreate() fonksiyonunu kullanarak çağırım yapabilirsiniz.


    Curio.eventCreate({eventKey: "Event Key", eventValue: "Event Value"});

                                

Sayfa Çıkış (End Hit)

Zorunlu Parametreler

  • pageTitle
  • path


Örnek Kullanım

Curio.hitEnd() fonksiyonunu kullanarak çağırım yapabilirsiniz.


    Curio.hitEnd({pageTitle: "Page Title", path: "Page URL"});

                                

Ziyareti Bitir (End Visit)

Sayfa kapatıldığı zaman ziyaret kendiğilinden sonlanacaktır. Sizin ziyareti bitirmek için herhangi bir şey yapmanıza gerek yoktur.



Dependencies

None



Version

0.2



License

GPL


Server API's

List Pushes

This API is used for listing push messages.


Request Parameter Definitions

  • profileId : ID of profile definition @Curio

  • timestamp: Current timestamp as long (in milliseconds)

  • hash: a token which is generated using HmacMD5 encryption on "profileId + timestamp + apiKey of the application @Curio

  • page: page number (10 push messages per page)



Request Sample

Request sample is as at the right side:



    GET /CurioAdmin/sapi/push/list/{profileId}/{timestamp}/{hash}/{page}

                                

Query Push Status

This API is used for sending push messages to devices.



Request Parameter Definitions

  • pushId : ID of sent push @Curio

  • timestamp : Current timestamp as long (in milliseconds)

  • hash : a token which is generated using HmacMD5 encryption on “pushId + timestamp + apiKey of the application @Curio”



Request Sample

Request sample is as at the right side:



    GET /sapi/push/status/{pushId}/{timestamp}/{hash}

                                

Response

Response is as at the right side.

  • pushState : The state of the push message which is being queried.

  • messages : List of sent messages with customId and token information.



    "pushState": "FINISHED",
    "messages": [
    {
    "customId": null,
    "token": "6a46c93468fc7510f85173f307aaa81e720789c2db6593c6e9448b5191cec263",
    "status": "SUCCESS",
    "sendDate": 1419580676189,
    "error": null,
    "result": "[1] transmitted {\"pId\":\"34737\",\"aps\":{\"sound\":\"default\",\"alert\":\"test\"}} on first attempt
    to token 6a46c..ec263"
    }
    ]

                                

States

  • RUNNING

  • CANCELLED

  • FINISHED

  • ERROR



Query User By CustomId

This API is used for getting Visitor information(s) by Custom ID.



Request Parameter Definitions

  • profileId : ID of profile definition @Curio

  • timestamp : Current timestamp as long (in milliseconds)

  • hash : a token which is generated using HmacMD5 encryption on “profileId + timestamp + apiKey of the application @Curio”

  • customId : customId to be queried is given as request body



Request Sample

Request sample is as at the right side:


  • POST /sapi/visitor/byCustomId/{profileId}/{timestamp}/{hash}

  • Content-Type: application/json

  • Request Body:

  • {customId}


Response

Response is as at the right side.



    ["trackingCode": "508RW8WA",
    "visitorCode": "f0cdc133-791a-4dde-8445-3478249b4939",
    "lastTime": 1422430549118,
    "ip": "127.0.0.1",
    "os": "Windows 7",
    "screen": "1920x1080",
    "visitCount": 396,
    "pushToken": "f0cdc133-791a-4dde-8445-3478249b4939",
    "customId": "5304556753"]

                                

Query User by Push Token

This API is used for getting Visitor information by Push Token.



Request Parameter Definitions

  • profileId : ID of profile definition @Curio

  • pushToken : Push token to be queried

  • timestamp : Current timestamp as long (in milliseconds)

  • hash : a token which is generated using HmacMD5 encryption on “profileId + timestamp + apiKey of the application @Curio”



Request Sample

Request sample is as at the right side:


  • GET /sapi/visitor/byPushToken/{profileId}/{pushToken}/{timestamp}/{hash}

  • Content-Type: application/x-www-form-urlencoded


Response

Response is as at the right side.



    "trackingCode": "508RW8WA",
    "visitorCode": "f0cdc133-791a-4dde-8445-3478249b4939",
    "lastTime": 1422430549118,
    "ip": "127.0.0.1",
    "os": "Windows 7",
    "screen": "1920x1080",
    "visitCount": 396,
    "pushToken": "f0cdc133-791a-4dde-8445-3478249b4939",
    "customId": "5304556753"

                                

Query User by Visitor Code

This API is used for getting Visitor information by Visitor Code.



Request Parameter Definitions

  • profileId : ID of profile definition @Curio

  • visitorCode : visitorCode of the user given by Curio-SDK

  • timestamp : Current timestamp as long (in milliseconds)

  • hash : a token which is generated using HmacMD5 encryption on “profileId + timestamp + apiKey of the application @Curio



Request Sample

Request sample is as at the right side:


  • GET/sapi/visitor/byVisitorCode/{profileId}/{visitorCode}/{timestamp}/{hash}

  • Content-Type: application/x-www-form-urlencoded


Response

Response is as at the right side.



    "trackingCode": "508RW8WA",
    "visitorCode": "f0cdc133-791a-4dde-8445-3478249b4939",
    "lastTime": 1422430549118,
    "ip": "127.0.0.1",
    "os": "Windows 7",
    "screen": "1920x1080",
    "visitCount": 396,
    "pushToken": "f0cdc133-791a-4dde-8445-3478249b4939",
    "customId": "5304556753"

                                

Send Push

This API is used for sending push messages to devices.



Request Parameter Definitions

  • profileId : ID of profile definition @Curio

  • timestamp : Current timestamp as long (in milliseconds)

  • hash : a token which is generated using HmacMD5 encryption on “profileId + timestamp + apiKey of the application @Curio



Request Sample

Request sample is as at the right side:


  • POST /CurioAdmin/sapi/push/send/{profileId}/{timestamp}/{hash}

  • Content-Type: application/json

  • Request Body: (For sending push to defined tokens)

{

"messageContent" : "Content of push message!",
"platforms" : [ {
      "profilePlatform" : {"id": 421} ,
      "messageParams" : [
          {"messageKey":"ios-key-1", "messageValue":"value-1"},
          {"messageKey":"ios-key-2", "messageValue":"value-2"}
       ]
    }, {
      "profilePlatform" : {"id": 420} ,
      "messageParams" : [
          {"messageKey":"android-key-2", "messageValue":"value-2"},
          {"messageKey":"android-key-1", "messageValue":"value-1"}
       ]
    } ],
"rules" : [ {
      "pushType" : "SELECTIVE", "tokens":["token-1", "token-2", "token-3"]}]
    } ]
                        

}

  • Request Body: (For sending push to defined customId's)

{

"messageContent" : "Content of push message!",
"platforms" : [ {
      "profilePlatform" : {"id": 421} ,
      "messageParams" : [
          {"messageKey":"ios-key-1", "messageValue":"value-1"},
          {"messageKey":"ios-key-2", "messageValue":"value-2"}
       ]
    }, {
      "profilePlatform" : {"id": 420} ,
      "messageParams" : [
          {"messageKey":"android-key-2", "messageValue":"value-2"},
          {"messageKey":"android-key-1", "messageValue":"value-1"}
       ]
    } ],
"rules" : [ {
      "pushType" : "CUSTOM_ID", "tokens":["customId-1", "customId-2", "customId-3"]}]
    } ]

}


JSON Field Definitions

  • messageContent : Content of push message to send.

  • platforms : Platform definitions for sending push ( with id & custom parameters for push)

  • rules : Must be set as “SELECTIVE” for sending push with tokens. Must be set as “CUSTOM_ID” for sending push with customId's.



Response

  • Long : the pushId which can be used for tracking the push status is returned.



    "trackingCode": "508RW8WA",
    "visitorCode": "f0cdc133-791a-4dde-8445-3478249b4939",
    "lastTime": 1422430549118,
    "ip": "127.0.0.1",
    "os": "Windows 7",
    "screen": "1920x1080",
    "visitCount": 396,
    "pushToken": "f0cdc133-791a-4dde-8445-3478249b4939",
    "customId": "5304556753"

                                

Other Rule Types

  • SELECTIVE

  • BULK

  • ONLINE

  • SCREEN

  • EVENT

  • DEVICE_TYPE

  • OPERATING_SYSTEM

  • VERSION

  • DEVICE_VENDOR

  • GSM_OPERATOR

  • DEVICE_MODEL

  • SCREEN_RESOLUTION



Server API Authentication Code

Oluşturulan hash'i kontrol etmek için : http://www.freeformatter.com/hmac-generator.html



    import javax.crypto.Mac;
    import javax.crypto.SecretKey;
    import javax.crypto.spec.SecretKeySpec;

    import org.apache.commons.codec.binary.Hex;

    public class TokenBasedAuthenticationMain {

    private String algorithm = "HmacMD5";

    public void authenticate(String apiKey, Long id, Long time) {

    try {
    SecretKey sk = new SecretKeySpec(apiKey.getBytes(), 0, apiKey.length(), algorithm);
    Mac mac = Mac.getInstance(algorithm);
    mac.init(sk);
    String key = new StringBuffer().append(id).append(time).append(apiKey).toString();

    byte[] result = mac.doFinal(key.getBytes());

    String token = new String(Hex.encodeHex(result));
    System.out.println("Id: "+ id + " Time:" + time + " ApiKey:" + apiKey + " key:" + key);
    System.out.println("token is: " + token);

    } catch (Exception e) {
    e.printStackTrace();
    }
    }

    }

                                

SDK API's

Event 2.0

This API is used for creating and ending event.


EVENT CREATE

Form Parameter Definitions

  • trackingCode :trackingCode of application defined @Curio
  • sessionCode :the code taken from session create operation
  • visitorCode :visitorCode of the user given by Curio-SDK
  • hitCode :hit code received from hit create response
  • eventKey :event key value
  • eventValue :event value
  • eventLabel :optional parameter event label value
  • sessionTimeout :optional parameter for session timeout


Request Sample

Request sample is as at the right side:


                            
                                
  • POST /v2/event/create
  • Content-Type: application/x-www-form-urlencoded
  • FormParameters: sessionCode=AAAA-BBBB-CCCC-DDDD&trackingCode=ASD1234&visitorCode=1111-2222-3333-4444&hitCode=5555-6666-7777-8888&eventKey=key&eventValue=value&eventLabel=label

EVENT END

Form Parameter Definitions

  • trackingCode :trackingCode of application defined @Curio
  • sessionCode :the code taken from session create operation
  • visitorCode :visitorCode of the user given by Curio-SDK
  • hitCode :hit code received from hit create response
  • eventKey :event key value
  • eventValue :event value
  • eventLabel :optional parameter event label value
  • sessionTimeout :optional parameter for session timeout


Request Sample

Request sample is as at the right side:


                                
                                    
  • POST /v2/event/create
  • Content-Type: application/x-www-form-urlencoded
  • FormParameters: sessionCode=AAAA-BBBB-CCCC-DDDD&trackingCode=ASD1234&visitorCode=1111-2222-3333-4444&hitCode=5555-6666-7777-8888&eventKey=key&eventValue=value&eventLabel=label

Set Location

This API is used for sending location information to Curio.


Form Parameter Definitions

  • trackingCode :trackingCode of application defined @Curio
  • visitorCode :visitorCode of the user given by Curio-SDK
  • sessionCode :the code taken from session create operation
  • lat :latitude
  • long :longitude


Request Sample

Request sample is as at the right side:


                                
                                    
  • POST /api/v2/location/set HTTP/1.1
  • Host: curiotest.turkcell.com.tr
  • Cache-Control: no-cache
  • Content-Type: application/x-www-form-urlencoded

trackingCode=508RW8WA&visitorCode=835a159a-1f0a-400d-b2a2-c7a81f3821de&sessionCode=2b7a1120-a534-11e4-8586-63ca635716aa&lat=41.005269999999996&long=28.97696

Set Push Data

This API is used for sending : push token of device to Curio & push open information to Curio.


Form Parameter Definitions

  • sessionCode :the code taken from session create operation

  • trackingCode :trackingCode of application defined @Curio

  • visitorCode :visitorCode of the user given by Curio-SDK

  • pushToken :push token taken from GCM & APNS

  • pushId :optional parameter for defining which push is opened

  • customId :optional parameter for setting a “CustomId” for the client



Request Sample

Request sample is as at the right side:


                                
                                    
  • POST /api/visitor/setPushData

  • Content-Type: application/x-www-form-urlencoded

  • FormParameters: sessionCode=GFGF-GFDG-RRER-FDFS&trackingCode=5L54XP88&visitorCode=DSDS-ERER-EREF-DGD&pushToken=6a46c93468fc7510f85173f307aaa81e720789c2db6593c6e9448b5191cec263&pushId=32621&customId=555555

Unregister Token & CustomId

This API is used for un-registering push token of device from Curio


Form Parameter Definitions

  • sessionCode : the code taken from session create operation
  • trackingCode : trackingCode of application defined @Curio
  • visitorCode : visitorCode of the user given by Curio-SDK
  • pushToken : optional push token taken from GCM & APNS
  • customId : optional parameter for setting a "CustomId" for the client
  • Note: At least pushToken or customId must be given in order to register token successfully.


Request Sample

Request sample is as at the right side:


                            
                                
  • POST /api/v2/visitor/unregister (/api/visitor/unregister)
  • Content-Type: application/x-www-form-urlencoded
  • FormParameters: sessionCode=GFGF-GFDG-RRER-FDFS&trackingCode=5L54XP88&visitorCode=DSDS-ERER-EREF-DGD&pushToken=6a46c93468fc7510f85173f307aaa81e720789c2db6593c6e9448b5191cec263&customId=555555