SDK kết nối Connection SDK

The SDK connects your app to GamifyEngine: initialize client, send events (track), and query points/tier as needed.

Flow: Config Event Type → Send event → Validate

The diagram below shows the required order: configure the event type first, then send events with the correct event_type and event_data. Data that does not match the config is rejected.

flowchart LR
  A["1. Client Admin
Config Event Type
(name, event_data_schema)"]
  B["2. App / SDK
track(event_type, event_data)"]
  C["3. Engine
Validate against event_data_schema"]
  D["OK → Rule award points"]
  E["Data invalid → Error"]
  A --> B --> C
  C --> D
  C --> E
  style D fill:#00d4aa22,stroke:#00d4aa,color:#00d4aa
  style E fill:#ef444422,stroke:#ef4444,color:#ef4444
            

event_type not configured or event_data does not match schema → Engine returns error, no processing.

Initialization (example):

// After obtaining apiKey (from backend/session)
GamifyEngine.init({
  apiBaseUrl: 'https://api.gamifyengine.com',
  apiKey: 'YOUR_API_KEY'
});

// Send event (track) — rules in Client Admin will process and award points
GamifyEngine.track('deposit_made', { amount: 100, currency: 'VND' });

Full event_data and event_data_schema examples (deposit_made, purchase): see Event Types — Example event_data_schema.

Rules & track event

Rules configured in Client Admin (e.g. when event deposit_made matches conditions, award points) apply automatically when you call track. Event name and payload must match the rule created in Client Admin.

Frontend integration

The official SDK name is GamifyEngine. Load the script from CDN or install via npm (CDN URL and package name are provided by the operator; or use the sample code in nodejs.zip). Call setConfig or init with apiBaseUrl and apiKey (prefer from backend per session). Then call track('event_name', data) whenever an action should be recorded. Do not hardcode API Key on the frontend.

Connection by language (backend)

Below are guides and code examples per platform: Node.js, Java, Python. Common flow: get apiBaseUrl + apiKey → Identify user (externalId → userId) → send event (user_id, event_type, event_data).

Node.js

Two integration options:

• Option 1 — SDK directly on frontend: Load SDK, call GamifyEngine.init({ apiBaseUrl, apiKey }) then GamifyEngine.track('event_type', payload). Prefer having the backend return the API Key per session.
• Option 2 — Via backend (recommended): Frontend calls your API (e.g. POST /api/fire-event); the Node.js backend identifies the user (Identify) and sends the event to Gamify — the Node.js backend can still fire events via the SDK (e.g. using nodejs.zip or the corresponding package). The demo-app uses this approach.

Download Node.js sample code:

• demo-app.zip — full demo app (React frontend + Node backend).
• nodejs.zip — SDK / Node.js integration source (backend).

Example 1 — Frontend sending event via backend (React, from demo-app)

In demo-app, the Event Simulator tab calls the backend API with externalId, eventType, and payload. The backend then identifies the user and sends the event to Gamify.

// Send event from frontend (user selected, e.g. externalId = 'demo-alice')
async function fireEvent() {
  const res = await fetch('/api/fire-event', {
    method:  'POST',
    headers: { 'Content-Type': 'application/json' },
    body:    JSON.stringify({
      externalId: user?.id,        // your system's user id
      eventType:  'purchase.completed',
      payload:    { order_id: 'ORD-001', total_amount: 999, item_count: 1 },
    }),
  });
  const data = await res.json();
  // data contains result from Gamify (userId, ...)
}

Example 2 — Backend receiving request and sending event to Gamify (Node, from demo-app)

The backend receives externalId, eventType, payload. Step 1: call Identify (create or get user) to obtain userId. Step 2: send the event with user_id, event_type, event_data. Exact endpoints and headers are provided by the GamifyEngine operator.

// (Core logic from demo-app server)
// 1) Identify user → get userId (UUID)
const identRes = await fetch(`${GAMIFY_API_URL}/v1/users?tenant=...`, {
  method:  'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${GAMIFY_API_KEY}` },
  body:    JSON.stringify({ externalId }),
});
const { data: userData } = await identRes.json();
const userId = userData?.id;

// 2) Send event
await fetch(`${GAMIFY_API_URL}/v1/events?tenant=...`, {
  method:  'POST',
  headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${GAMIFY_API_KEY}` },
  body:    JSON.stringify({
    user_id:    userId,
    event_type: eventType,
    event_data: payload || {},
    source:     'demo-app',
  }),
});

Example 3 — Mount Widget (from demo-app)

Demo-app mounts the Widget with apiBaseUrl, apiKey, and externalId from config (backend). When the user changes, it unmounts and mounts again with the new externalId.

// config from /api/config (backend returns gamifyApiUrl, gamifyApiKey, demoUsers)
useEffect(() => {
  if (!config || !user) return;
  const instance = globalThis.GamifyWidget.mount({
    apiBaseUrl:  config.gamifyApiUrl,
    apiKey:      config.gamifyApiKey,
    externalId:  user.id,
    tenant:      config.gamifyTenant || undefined,
    theme:       'cyberpunk',
    fabPosition: 'right-bottom',
    showToasts:  true,
  });
  return () => instance?.unmount?.();
}, [user?.id, config]);

Java

A Java backend (Spring Boot, Jakarta EE, or plain Java) connects to GamifyEngine: (1) Call Identify with externalId to get userId. (2) Send the event with user_id, event_type, event_data. Use an HTTP client (Java 11+ HttpClient, RestTemplate, or WebClient) with header Authorization: Bearer <API_KEY>. Base URL and endpoints are provided by the operator.

// Example structure (Java 11+ HttpClient) — replace BASE_URL, API_KEY, tenant per environment
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class GamifyClient {
    private final String baseUrl;
    private final String apiKey;
    private final String tenant;
    private final HttpClient http = HttpClient.newHttpClient();

    public GamifyClient(String baseUrl, String apiKey, String tenant) {
        this.baseUrl = baseUrl;
        this.apiKey = apiKey;
        this.tenant = tenant;
    }

    public String identify(String externalId) throws Exception {
        var body = String.format("{\"externalId\":\"%s\"}", externalId);
        var req = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/v1/users?tenant=" + tenant))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiKey)
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        var res = http.send(req, HttpResponse.BodyHandlers.ofString());
        return parseUserId(res.body());  // parse data.id
    }

    public void trackEvent(String userId, String eventType, String eventDataJson) throws Exception {
        var body = String.format(
            "{\"user_id\":\"%s\",\"event_type\":\"%s\",\"event_data\":%s,\"source\":\"java\"}",
            userId, eventType, eventDataJson != null ? eventDataJson : "{}");
        var req = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/v1/events?tenant=" + tenant))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + apiKey)
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();
        http.send(req, HttpResponse.BodyHandlers.ofString());
    }
}

Python

A Python backend (Django, FastAPI, Flask, or script) connects to GamifyEngine: (1) Call Identify with external_id to get user_id. (2) Send the event with user_id, event_type, event_data. Use requests or httpx with header Authorization: Bearer <API_KEY>. Base URL and endpoints are provided by the operator.

# Example (Python 3, requests) — replace BASE_URL, API_KEY, tenant per environment
import requests

class GamifyClient:
    def __init__(self, base_url: str, api_key: str, tenant: str = ""):
        self.base_url = base_url.rstrip("/")
        self.api_key = api_key
        self.tenant = tenant
        self.session = requests.Session()
        self.session.headers["Authorization"] = f"Bearer {api_key}"
        self.session.headers["Content-Type"] = "application/json"

    def identify(self, external_id: str) -> str:
        url = f"{self.base_url}/v1/users"
        if self.tenant:
            url += f"?tenant={self.tenant}"
        r = self.session.post(url, json={"externalId": external_id})
        r.raise_for_status()
        return r.json()["data"]["id"]

    def track_event(self, user_id: str, event_type: str, event_data: dict = None):
        url = f"{self.base_url}/v1/events"
        if self.tenant:
            url += f"?tenant={self.tenant}"
        body = {
            "user_id": user_id,
            "event_type": event_type,
            "event_data": event_data or {},
            "source": "python",
        }
        r = self.session.post(url, json=body)
        r.raise_for_status()

# Usage
client = GamifyClient("https://api.example.com", "YOUR_API_KEY", "my-tenant")
user_id = client.identify("user-123")
client.track_event(user_id, "purchase.completed", {"order_id": "ORD-001", "amount": 999})