Skip to content

README.md

Latest commit

 

History

History
238 lines (183 loc) · 7.04 KB

README.md

File metadata and controls

238 lines (183 loc) · 7.04 KB

GA-SDK-CPP

GameAnalytics C++ SDK

Documentation can be found here.

Supported platforms:

  • Mac OSX
  • Windows 32-bit and 64-bit
  • Linux

Dependencies

  • python 3.6 or higher
  • cmake 3.20 or higher
  • Mac: XCode
  • Windows: Visual Studio 2017 or later
  • Linux: clang or gcc

Changelog

See the full CHANGELOG for detailed version history.

How to build

Run setup.py with the required arguments for your platform:

python setup.py --platform {linux_x64,linux_x86,osx,win32,win64,uwp} [--cfg {Release,Debug}] [--compiler {gcc,clang}] [--shared] [--build] [--test] [--coverage]
Argument Values Description
--platform linux_x64, linux_x86, osx, win32, win64, uwp Target platform (required)
--cfg Release, Debug Build configuration (default: Debug)
--compiler gcc, clang Compiler selection — Linux only (default: clang)
--shared — Build a shared library (.dll/.so/.dylib) instead of a static library
--build — Execute the build step
--test — Execute the test step (not available with --shared)
--coverage — Generate code coverage report (not available with --shared)

Examples

Static library (default):

python setup.py --platform osx --cfg Release --build --test

Shared library (e.g. for Unity native plugin):

python setup.py --platform win64 --cfg Release --shared --build
python setup.py --platform osx --cfg Release --shared --build
python setup.py --platform linux_x64 --cfg Release --shared --build
python setup.py --platform linux_x64 --compiler gcc --cfg Release --shared --build

The generated project and build artifacts can be found inside the build folder. Packaged output (library + headers) is placed in build/package/.

Lib Dependencies

  • crossguid (as source) - Cross platform library to generate a Guid.
  • cryptoC++ (as source) - collection of functions and classes for cryptography related tasks.
  • curl (as binary) - library used to make HTTP requests.
  • nlohmann json (as source) - lightweight C++ library for manipulating JSON values including serialization and deserialization.
  • openssl (as binary) - used by curl to make HTTPS requests.
  • SQLite (as source) - SQLite is a software library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine.

as source means the dependency will be compiled with the project itself, as binary means the dependency is prebuild and will be linked to the project

Usage of the SDK

Static library (C++ API)

Include the GameAnalytics header file wherever you are using the SDK:

 #include "GameAnalytics/GameAnalytics.h"

Shared library / Unity native plugin (C API)

When building with --shared / -DGA_SHARED_LIB=ON, the SDK exposes a C API via GameAnalyticsExtern.h. This is the intended integration path for Unity (P/Invoke) and other managed runtimes.

Include the header in your native wrapper:

#include "GameAnalytics/GameAnalyticsExtern.h"

From Unity C#, import via [DllImport]:

[DllImport("GameAnalytics")]
private static extern void gameAnalytics_initialize(string gameKey, string gameSecret);

Note: Always call gameAnalytics_freeString(ptr) on any const char* returned by the C API to avoid memory leaks.

Custom log handler

If you want to use your own custom log handler here is how it is done:

C++ API:

void logHandler(std::string const& message, gameanalytics::EGALoggerMessageType type)
{
    // add your logging in here
}

gameanalytics::GameAnalytics::configureCustomLogHandler(logHandler);

C API (shared lib):

void myLogHandler(const char* message, GALoggerMessageType type)
{
    // add your logging in here
}

gameAnalytics_configureCustomLogHandler(myLogHandler);

Custom HTTP client

By default, the SDK uses cURL for HTTP requests. If you need to use a different HTTP library (e.g. on consoles or custom platforms), you can provide your own implementation by subclassing GAHttpClient:

#include "GameAnalytics/GAHttpClient.h"

class MyHttpClient : public gameanalytics::GAHttpClient
{
public:
    void initialize() override
    {
        // Set up your HTTP library
    }

    void cleanup() override
    {
        // Tear down your HTTP library
    }

    Response sendRequest(
        std::string const& url,
        std::string const& auth,
        std::vector<uint8_t> const& payloadData,
        bool useGzip,
        void* userData) override
    {
        Response response;

        // Use your HTTP library to POST payloadData to url.
        // Set the following headers:
        //   - auth (e.g. "Authorization: ...")
        //   - "Content-Type: application/json"
        //   - "Content-Encoding: gzip" (if useGzip is true)
        //
        // Fill in response.code with the HTTP status code.
        // Fill in response.packet with the response body bytes.

        return response;
    }
};

Register it before calling initialize():

gameanalytics::GameAnalytics::configureHttpClient(std::make_unique<MyHttpClient>());
gameanalytics::GameAnalytics::initialize("<your game key>", "<your secret key>");

If configureHttpClient is not called, the built-in cURL implementation is used.

Configuration

Example:

 gameanalytics::GameAnalytics::setEnabledInfoLog(true);
 gameanalytics::GameAnalytics::setEnabledVerboseLog(true);

 gameanalytics::GameAnalytics::configureBuild("0.10");

 {
     std::vector<std::string> list;
     list.push_back("gems");
     list.push_back("gold");
     gameanalytics::GameAnalytics::configureAvailableResourceCurrencies(list);
 }
 {
     std::vector<std::string> list;
     list.push_back("boost");
     list.push_back("lives");
     gameanalytics::GameAnalytics::configureAvailableResourceItemTypes(list);
 }
 {
     std::vector<std::string> list;
     list.push_back("ninja");
     list.push_back("samurai");
     gameanalytics::GameAnalytics::configureAvailableCustomDimensions01(list);
 }
 {
     std::vector<std::string> list;
     list.push_back("whale");
     list.push_back("dolphin");
     gameanalytics::GameAnalytics::configureAvailableCustomDimensions02(list);
 }
 {
     std::vector<std::string> list;
     list.push_back("horde");
     list.push_back("alliance");
     gameanalytics::GameAnalytics::configureAvailableCustomDimensions03(list);
 }

Initialization

Example:

 gameanalytics::GameAnalytics::initialize("<your game key>", "<your secret key>");

Send events

Example:

 gameanalytics::GameAnalytics::addDesignEvent("testEvent");
 gameanalytics::GameAnalytics::addBusinessEvent("USD", 100, "boost", "super_boost", "shop");
 gameanalytics::GameAnalytics::addResourceEvent(gameanalytics::Source, "gems", 10, "lives", "extra_life");
 gameanalytics::GameAnalytics::addProgressionEvent(gameanalytics::Start, "progression01", "progression02");