craigmj / countly-sdk-blackberry10-cascades

A BlackBerry 10 Cascades SDK for count.ly

countly-sdk-blackberry10-cascades

VERSION: beta 1.0 for C++ (alpha for QML)

A BlackBerry 10 Cascades SDK for count.ly

Installing Countly BlackBerry 10 Cascades SDK

1. Add all the .cpp and .hpp files in the sdk/ directory to your project (I symlink them).
2. Add the following line to your .pro file:
   LIBS += -lbb -lbbdata -lbbplatform -lbbdevice
3. Add the Internet (access_internet) and Device Identifying Information (read_device_identifying_information) permissions to your bar-descriptor.xml

USAGE

1. At the top of your main.cpp file:
   #include "Countly.hpp"
2. Just after your application is created in your main.cpp file, add:
   countly::CountlyInit(&app, "http://10.0.0.6/", "73c1dbd6b5a917bfb54f50a87f2dc11fca84d0b9");
   Where the 10.0.0.6 is the address of your Count.ly server, and the 73... is your App Key from your Count.ly server
3. Wherever you want to log a Count.ly event:
   
   1. Remember to #include "Countly.hpp"
   2. countly::CountlyEvent event(parentQObject, "key"); event.set("segment_key", "segment_value"); event.send();

Note: If you use Countly Cloud, you should set your host to https://cloud.count.ly in step 2.

PERSISTENCE

By default, events are persisted to a sqlite database that the SDK will create in your app's data folder. Any events that are not successfully delivered, are persisted to this database, and the application will attempt to deliver them on the next execution.

Because one does not want to fill a user's device with events, events are deleted if:

1. An attempt to deliver them receives a JSON reponse from the server, but it is not 'Success': in this case, we presume there is something wrong with the event, and discard it.
2. There are more than 5 'sessions' (defined as a start of the app) and the event is part of a session that is more than 2 weeks old.

You can change these parameters by providing additional parameters to the CountlyInit function. It's full signature is:

void CountlyInit(bb::cascades::Application *app, const QString &server, const QString &appKey, bool useDatabase=true, long maxPersistedSessions=-1, long sessionsExpireAfter=-1);

The last 3 parameters are:

useDatabase

Set to false if you don't want to persist events to the database.

maxPersistedSessions

Set to the maximum number of sessions that you want persisted. Note that sessions will only be discarded when there are more than that number AND they have exceeded the expiry period.

sessionsExpireAfter

The number of seconds after which a session is considered expired. After this period, AND if there are more than maxPersistedSessions, the excess sessions will be discarded.

EXAMPLE

See project example in countly-sdk-example directory for example application.

LOGGING

The Count.ly framework logs through CountlyLog::log(..) method. Easy location to change or reroute logging. By default, no logs are written when in a Release build.

TODOS

1. It needs testing!
2. QML integration only happens through calls to C++. I'm trying to work out a better method.

LICENCE

Please see the LICENCE file