Usage

This guide outlines the client-side plugin setup and general usage.

Installation

If you don't already have it, get the Coronium Core Plugin from the Corona Marketplace.

Add the plugin

Add the plugin by adding an entry to the plugins table of build.settings file:

settings =
{
    plugins =
    {
        ["plugin.coronium-core"] =
        {
            publisherId = "com.develephant"
        },
    },
}

Require the plugin

To gain access to the plugins functionality, require it like so in your Lua file:

local core = require("plugin.coronium-core")

You're now ready to use the Coronium Core plugin.

Plugin Overview

The Coronium Core client plugin provides an interface to your Coronium Core server. The client contains various data modules, a file transfer module, user management, and analytics module and the ability to call your own custom methods built with the server-side API module.

Coronium Core Required

You will need a running Coronium Core server before being able to utilize the client plugin. You can install the server on DigitalOcean or Amazon EC2.

Before continuing, make sure you have read through the Installation section.

In this example, we will use the main.lua of a Corona project as a reference point, though you may require and use the client plugin in whichever file it is most useful.

Initialization

After you have required the Coronium Core plugin into your Corona project, you must initalize it using the core.init method. You will provide the init method the following keys in a table.

Core Init Keys

Name	Description	Type	Required
version	The Coronium Plugin revision. Set to 2 to support server features in v2.6.0 or better. Set to 1 for older versions.	Number	Y
server	The Coronium Core server address.	String	Y
key	The Coronium Core server key.	String	Y
scope	A unique application name for your Corona project. See Application Scope below.	String	Y
api	The server-side API Project name to run custom api methods against (see Server-side API).	String	N

Application Scope

Every Corona project must provide a unique "application scope" to the Coronium Core initialization. This scope allows you to group users and metrics to each application so that you can visualize them individually via the Webmin, and for other purposes.

Provide the application scope name to the scope parameter of the core.init initialzation method. Learn how to set up scopes in the next section.

Example

local core = require("plugin.coronium-core")

core.init({
  version = 2,
  server = "https://your.coronium.host",
  key = "03624656-ca90-11e7-b8d4-fb59abeb4c03",
  scope = "<app-scope>" --Adding the scope parameter
})

Don't Change The Scope!

Once the scope is set, do not change it for that particular application. If you do, you will lose user and metric associations.

Enabling Scopes

To add a new scope, select the Scopes section in the Webmin and then click New Scope and enter the requested information.

It is important to choose a short but descriptive application scope name that is unique from your other application scopes.

Scopes are only relavant to the User and Analytics modules.

Scope Permissions

As an added layer of security, you can set permissions for client-side methods using Scope permissions.

To adjust permissions go to the Scopes section of the Webmin and click on a scope name. Once you are on the scope detail page, there will be a Scope Permissions section.

Permissions are divided by module. Make sure to save permissions changes for each module section by clicking the Save button at the bottom of each section.

Custom API Init

To utilize custom server-side api methods, first make sure you have a server-side project set up. Provide the API Project name to the api parameter in the initialization. See the server-side API module for more information.

Example

local core = require("plugin.coronium-core")

core.init({
  version = 2,
  server = "https://your.coronium.host",
  key = "03624656-ca90-11e7-b8d4-fb59abeb4c03",
  scope = "Fun Run",
  api = "funrun"
})

Response Events

When calling a module or api method, you must supply a listener function to recieve the response event back from the server:

Basic api listener

local function apiResponse( evt )
  if evt.error then
    print(evt.error) --contains error string, if any.
  else
    local res = evt.result --evt.result contains the server response
  end

  print(evt.tt) --contains request round trip time
end

All response events will contain either an error key, or the successful response in the result key.

All response events contain a tt key. See below for more details on this key.

Event Keys

Some modules may have additional event keys. See each modules documentation for event responses.

error

The error key will always be a string with the error message, or nil if no error is present. If there is an error, often there will also be a status key with a numeric code.

result

The result key data depends on the module or api method. See each modules documentation to determine what the result key might hold.

tt

The tt key allows you to see the "trip time" for the request. This is the total round trip time in milliseconds from the start of the client network request, to the final client response.

Debug Responses

To debug response events during development, use the core.debug method (see below).

Debug Responses

Sometimes it can be nice to see the full response (including errors) without have to write the full logic in the event listener.

To make this simpler, you can use the core.debug method.

Example

local function apiResponse( evt )
  core.debug( evt )
end

core.users.login({
  username = 'Wordy',
  password = '1234'
}, apiResponse)

The following will be output to the Corona console:

result:
  active: true
  email: sleeptankxyz@gmail.com
  group: foodies
  scope: Space Race
  user_id: c369637a-cb27-44ee-aeaf-ca263daa49d5
  username: Wordy
  validated: true
  tt: 64.401

API Methods

Depending on the module you are addressing, use the following namespaces on the core object.

--Standard Client Side Module Methods
core.<module>.<method>([input_params,] listener)

--Custom Server Side API Methods
core.api.<method>([input_params,] listener)

Parameters

Name	Description	Type	Required
input_params	The parameters to pass to the method.	Table	N
listener	The response listener callback function.	Function	Y

Special Note

If a method does not require a input_params table, you can either pass any empty table, or omit the parameter table all together, supplying just the listener.

Examples

Client side data module

local function apiResponse( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result) --data object id
  end
end

core.data.save({
  source = "users",
  data = {
    name = "Tammy",
    age = 34,
    active = true
  }
},  apiResponse)

Custom server-side api method

local function apiResponse( evt )
  if evt.error then
    print(evt.error)
  else
    print(evt.result.name) -- Jimmy
  end
end

core.api.echo({name="Jimmy"}, apiResponse)

See each client-side module documentation for full usage instructions and examples.