Getting Started - GravitumLabs/gravitum-corona-sdk GitHub Wiki

Gravitum is a high volume and reliable player retention platform for mobile applications. We support all major native and mobile platforms by providing dedicated SDKs for each platform. And an online dashboard for analytics monitoring and push campaigns flow setup.

This is a getting started guide for utilizing Gravitum SDK for Corona enterprise.

Platform Specific Configuration

  • If you will be releasing your game on Android platform, follow this guide to set up the required settings in Google Play Developer Console for Push notifications and android installation steps below for usage.

  • If you will be releasing your game on iOS platform, follow this guide to set up the required settings in the Apple Developer Console for Push Notifications and iOS installation steps below for usage.

SDK Installation for Android

Import the Gravitum Corona enterprise plugin jar to your Corona enterprise project like any other jar library. You will also need to import the gravitum sdk core android library and other dependencies as described on https://github.com/GravitumLabs/gravitum-android-sdk/wiki/Getting-Started.

You can find the App Token and App Secret in your Gravitum Developer Dashboard. Sender ID you can find in your Google Play Developer Console (more information here).

Now you are ready to start programming.

Programming guidelines

Add this during the initialization phase of the App or when you have all the relevant data available, if you need to gather the optional metadata.

analytics.SetUserId("<UserId>")
analytics.SetUserName("<UserName>")
analytics.SetDevicePushToken("<3rdPartyPushToken>")
analytics.SetFacebookId("<FacebookId>")
analytics.SetUserGender("female") --or "male"
analytics.SetUserBirthday(06,12,1986) -- dd,MM,yyyy
local custom = {} -- Your own custom values
custom.val1 = "test1"
custom.val2 = 5567
analytics.SetCustomFields(custom)	
analytics.init("<Project Token>","<Project Secret>","<GCM Id>",listener) -- Gravitum Event listener

Important: All the method calls before analytics.Init are optional methods. These methods are used to set additional user metadata. Let's take a brief review of the optional methods.

  • The very first optional method is SetUserId. You may provide your own user id in certain cases (e.g. you want to use Google Play Services/Game Center player id as the unique user id for Gravitum service or you have your own web server with the custom player authentication), otherwise, it will be generated automatically. Just make sure, that the Id you provide will be unique for each user.

  • To provide the user name use SetUserName method with the string name. Unlike the used Id, user name may not be unique. What name to provide is up to you without any restrictions.

  • Set user Facebook Id via SetFacebookId method call. The common approach if to get the user Facebook Id from Facebook SDK itself and provide it to Gravitum Analytics.

  • If you have your own push notifications service implementation, you may use SetDevicePushToken method to provide the unique Id for each user device. If you don't pass any particular token, the Gravitum will generate push token by itself according to the Google Cloud Messaging SenderId you provided with the Init method.

  • Last two SetBirthday and SetGender speak for themselves. Provide them as shown above in the example.

  • You can set custom unique fields for each user. These fields will be used for filtering the segments from the audience of your application. Important: You can set up to 15 custom fields for each user. Only supported on Android.

Now we are done with SDK initialization and are ready to setup events tracking.

To send custom event use following code sample. You can provide any event data you want as a Dictionary. What data to send with analytics event depends on your game project. It is important that you think through the types of events you want to send up and the structure of the data associated with each event.

analytics.sendEvent("first_test_message")
local data = {}
data.name = "testname"
data.value = 2123
data.boolval = true
data.floatval = 12.323123
analytics.sendEvent("datatable_test",data)

One more specific Analytics event type is Monetary event. The common approach is to track In-App Purchases with this event. Please send this event for every successful In-App Purchase, provide the product Id, price and the currency code of the real In-App Purchase. All these events are colected and presented in the Purchases section of the Gravitum Dashboard.

analytics.sendPurchaseEvent("buycoins",0.99,"USD")

Important: For Push Notification you will need to add the udpates to AndroidManifest file and permissions as described on here: Android SDK Setup

SDK Installation for iOS

Import the Gravitum Corona Enterprise iOS plugin to your Xcode project like any other .a library and import the Gravitum analytics library as described on https://github.com/GravitumLabs/gravitum-ios-sdk/wiki/Getting%20Started

Add this during the initialization phase of the App or when you have all the relevant data available, if you need to gather the optional metadata. The initialization step for iOS is a bit different so please note the example below.

local iOSData = {}
iOSData.userId = "<UserId>"
iOSData.userName = "<UserName>"
iOSData.gender = "female" -- or "male"
iOSData.facebookId = "<FacebookId>"
iOSData.devicePushToken = "<APNs Push Token or 3rdParty>" --
analytics.SetUserBirthday(17,11,1986)
analytics.initWithData("<Project Token>","<Project Secret>","<Reserved for Future>",iOSData,listener) -- Gravitum Event listener

Also add the following to your build.settings file in the Corona project.

iphone =
    {
        plist =
            {
                CoronaDelegates = { "GravitumNotificationsDelegate" },
            }
    }

Important: For notification support with APNs, use a lua listener as under to ensure initialization and registration are done correctly.

local function onNotification(event)
    if event.type == "remoteRegistration" then
        local message = "This app has successfully registered for APNs."
        native.showAlert("Information", message, { "OK" })
    else
        -- A push notification has just been received. Print it to the log.
        print("### --- Notification Event ---")
        local message = "Push notification received from APNs."
        native.showAlert("Information", message, { "OK" })
    end
end
Runtime:addEventListener("notification", onNotification)

Important: For sending events and tracking, the calls are same as for Android, so please refer to the Android guide above which also covers details of optional parameters.

Important: You shouldn't send any event for tracking session length. All the duration tracking events will be sent under the hood. Game session metrics are available on your Gravitum Developer Dashboard.

⚠️ **GitHub.com Fallback** ⚠️