SDK connector

SDK connectors are paired with an SDK that can be used within a website or application to send events to Krenalis. For example, the JavaScript connector is paired with the JavaScript SDK, which can be integrated into a website or web application to collect and send events to Krenalis.

An SDK connector doesn't need to implement specific methods to send events. All event handling and transmission logic resides in the SDK paired with the connector. Therefore, if you develop an SDK connector, you must also implement the corresponding SDK to be used in the applications it targets.

Like other types of connectors, SDK connectors are written in Go. A connector is a Go module that implements specific functions and methods.

Quick start

In the creation of a new Go module, for your SDK connector, you can utilize the following template by pasting it into a Go file. Customize the template with your desired package name, type name, and pertinent connector information:

// Package javascript implements a connector for JavaScript.
package javascript

import (
    "github.com/krenalis/krenalis/connectors"
)

func init() {
    connectors.RegisterSDK(connectors.SDKSpec{
        Code:                "javascript",
        Label:               "JavaScript",
        Categories:          connectors.CategorySDK | connectors.CategoryWebsite,
        Strategies:          true,
        FallbackToRequestIP: true,
        Documentation: connectors.Documentation{
            Source: connectors.RoleDocumentation{
                Summary:  "Import events and users using JavaScript",
            },
       },
    }, New)
}

type JavaScript struct {
    // Your connector fields.
}

// New returns a new connector instance for JavaScript.
func New(env *connectors.SDKEnv) (*JavaScript, error) {
    // ...
}

Implementation

Let's explore how to implement a SDK connector, for example for JavaScript.

First create a Go module:

mkdir javascript
cd javascript
go mod init javascript

Then add a Go file to the new directory. For example copy the previous template file.

Later on, you can build an executable with your connector.

About the connector

The SDKSpec type describes the specification of the SDK connector:

• Code: unique identifier in kebab-case (a-z0-9-), e.g. "javascript", "android", "dotnet".
• Label: display label shown in the Admin console, typically the name of the language or platform (e.g. "JavaScript", "Android", ".NET").
• Categories: the categories the connector belongs to. There must be at least one category, but for an SDK connector it should be only connectors.CategorySaaS. You can also add the connectors.CategoryWebsite category if the paired SDK can be used for websites.
• Strategies: whether this connector supports user strategies.
• FallbackToRequestIP: whether to use the request IP as the event IP if context.ip was not provided.

This information is passed to the RegisterSDK function that, executed during package initialization, registers the SDK connector:

func init() {
    connectors.RegisterSDK(connectors.SDKSpec{
        Code:                "javascript",
        Label:               "JavaScript",
        Categories:          connectors.CategorySDK | connectors.CategoryWebsite,
        Strategies:          true,
        FallbackToRequestIP: true,
        Documentation: connectors.Documentation{
            Source: connectors.RoleDocumentation{
                Summary:  "Import events and users using JavaScript",
            },
       },
    }, New)
}

Constructor

The second argument supplied to the RegisterSDK function is the function utilized for creating an SDK instance:

func New(env *connectors.SDKEnv) (*JavaScript, error)

This function accepts an SDK environment and yields a value representing your custom type.

The structure of SDKEnv is defined as follows:

// SDKEnv is the environment for an application SDK connector.
type SDKEnv struct {

    // Settings holds the raw settings data.
    Settings json.Value

    // SetSettings is the function used to update the settings.
    SetSettings SetSettingsFunc
}

• Settings: Contains the instance settings in JSON format. Further details on how the connector defines its settings will be discussed later.
• SetSettings: A function that enables the connector to update its settings as necessary.