I've blown this thing up a bit, so the below is no longer accurate.
Hi! This is the repository of Helios' Keen IO plugin. This is a write-only plugin written specifically for Unity3D with caching support (no Keen administration/read operations. solely one-way metric writing to Keen servers).
Caching feature can come in handy if you are using Keen IO in situations where Internet connectivity is sparse. This library caches your calls and sends them at a later time when connection is back online and stable.
Remember to change your runtime configuration from .NET subset to .NET in build settings before building your Unity3D project (not needed if you are not using the SQLite cache provider).
Binaries for SQLite on Windows are checked in (x86 and x86_64). You may obtain additional binaries for other platforms from SQLite project's website if you need to.
Virtually you can use this library on all platforms as long as you take care of providing a native build of sqlite3
. A binary is checked in for followin tested platforms:
- Windows x86
- Windows x64
- OSX x64
- iOS x64
On iOS, you must use Application.persistentDataPath
as your cache directory (this is one of the fewest directories write-able on iOS devices).
You may begin by importing the latest stable release .unitypackage
. There is an example scene and an example script (MetricsExample.cs
) in this repository which shows you how to use this plugin.
Start by having an instance of Helios.Keen.Client
which is a MonoBehaviour
:
var MetricsClient = gameObject.AddComponent<Helios.Keen.Client>();
Then provide it your project's specific settings:
MetricsClient.Settings = new Helios.Keen.Client.Config
{
/* [REQUIRED] Keen.IO project id, Get this from Keen dashboard */
ProjectId = "none",
/* [REQUIRED] Keen.IO write key, Get this from Keen dashboard */
WriteKey = "none",
/* [OPTIONAL] Attempt to sweep the cache every 45 seconds */
CacheSweepInterval = 45.0f,
/* [OPTIONAL] In every sweep attempt pop 10 cache entries */
CacheSweepCount = 10,
/* [OPTIONAL] This is the callback per Client's event emission */
EventCallback = OnKeenClientEvent,
/* [OPTIONAL] If not provided, cache is turned off */
CacheInstance = new Helios.Keen.Cache.Sqlite("path/to/db")
};
And start sending events:
// This is an example of sending Helios specific events
MetricsClient.SendQuizEvent(new Helios.Keen.Client.QuizEvent
{
quizId = "IQ test",
quizResult = "failed",
experienceData = new Helios.Keen.Client.ExperienceData
{
experienceLabel = "Keen Plugin",
versionNumber = "1.0.0",
location = "never land"
}
});
// This is an example of using custom data types
MetricsClient.SendEvent("custom_event", new CustomData
{
data_member_1 = "test string",
data_member_2 = 25000.0f,
data_member_3 = new CustomNestedData
{
data_member_1 = "\"nested\" string",
data_member_2 = 25000d,
}
});
Don't forget to cleanup after yourself! (In case you used AddComponent
)
Destroy(MetricsClient);
Take a look at MetricsExample.cs
for more in-depth usage examples.
Also SessionExample.cs
shows you how to use StateAwareClient
class.
There is an extremely simplistic JSON serializer built into this library (about 60 lines of code with comments!) which provides a portable and backwards compatible C# implementation for serializing FLAT CLASSES, FLAT STRUCTS, and POD data types.
This means the serializer does not support fancy features such as inheritance. You can absolutely use a custom and more advanced JSON serializer; if you absolutely need to work with more complicated data types. Here's an example of using Unity 5.3's JSON serializer and using the SendEvent(string, string)
overload:
MetricsClient.SendSession("eventName", JsonUtility.ToJson(myComplexObject));
There are two important namespaces:
Helios.Keen
Helios.Keen.Cache
All cache implementations go under Helios.Keen.Cache
namespace. For now it only contains a SQLite cache implementation. This is an optional dependency. You are more than welcome to strip it out and provide a custom ICacheProvider
implementation of your own.
SQLite cache provider has a dependency on native sqlite3
binaries. They are checked in under Plugins
folder for Windows 32/64 bit and Android x86/armabi-v7. Note that SQLite provider is optional. You can provide your own caching mechanism.
class Helios.Keen.Client
is the actual client library. class Helios.Keen.Cache.Sqlite
is the SQLite cache provider to be used optionally with the client instance.
For optimal performance I highly recommend multiple instances of Helios.Keen.Client
in conjunction with Helios.Keen.Cache.Sqlite
instances. Each instance of Helios.Keen.Cache.Sqlite
must point to a separate database for optimal performance otherwise it causes race conditions/lock issues between multiple instances pointing to the same database.
You may also consider installing Visual C++ Redistributable for Visual Studio 2015 if you are using binaries provided in this repository under Windows.
Helios internally uses some conventions when dealing with Keen.IO. These conventions can be found in Helios/Keen/ClientHeliosExtension.cs
.