ledge-typescript-api-client

This is an early version of Ledge Developer Docs. Our API is still in active early stages of development and is subject to change.

Welcome to Ledge Developer Docs. We are constantly improving and we'd greatly appreciate your feedback, so please feel free to create issues or chat with [email protected].

[COMING SOON] We also have a developer chat in our Discord.

Table of Contents

• Important Notes
• Quick Start
  • Requirements
  • 1. Install the npm package
  • 2. Setup Configuration
  • 3. Register User
  • 4. Track User Activity
• SDK Reference
  • registerUser
  • trackActivity
  • trackBatchActivitiesByUser

Important Notes

• We recommend you use our SDK on the server side for performance and security.
• We recommend you track user activity in batches.
• Have our SDK integrated and ready for testing 1-2 weeks before the event start date.
• Register your users as early as possible to begin tracking their in game activity.

Quick Start

Requirements:

1. API_KEY from one of the Ledge Admins, get in contact ([email protected])!
2. API_URL from one of the Ledge Admins, get in contact ([email protected])!

1. Install our npm package at npm package

npm i @ledgelabs/typescript-api-client

or

yarn add @ledgelabs/typescript-api-client

2. Setup Configuration

import { Configuration } from "@ledgelabs/typescript-api-client";

const config = new Configuration({
  apiKey: API_KEY
  basePath: API_URL,
});

3. Register user so we can track activity

• Register this user as soon as possible, ideally when they open the game. so that we can start tracking player activity and reward progress towards quests.
• Original creation date is when this user first joined your game.

import { ExternalApi } from "@ledgelabs/typescript-api-client";

const ledgeApi = new ExternalApi(config);

await ledgeApi.registerUser("fake-api-key", {
    userId: "fake-user-id",
    username: "random-fake-username",
    originalCreationDate: new Date().toISOString(),
});

4. Track in-game user activity

await ledgeApi.trackActivity({
    activityId: "kill-5-ogres",
    occurrence: "2024-04-20T18:18:03.369Z",
    userId: "fake-user-id",
    count: 1,
  });

SDK Reference

Description

Registers this user (externally) with Ledge, so we can begin tracking their in game activity

Ideally, call this method as soon as this user starts the game.

Params

export interface ExternalUser {
    originalCreationDate?: string;
    userId: string;
    username: string;
}

originalCreationDate is used for attribution purposes and revenue sharing but is optional, leaving this undefined will simply not attribute this user's acquisition and consequently no revenue shared. Input this parameter if unsure.

username does not need to be unique.

userId must be unique for each player within a game (per API_KEY)

Return Type

export interface RegisterUser200Response {
    linkingCode: string;
    ledgeLink: string;
}

linkingCode is a unique code per user per game, used to identify your registered user with a Ledge account.

ledgeLink is a link to Ledge login page with a linking code.

Description

Tracks a single game activity/event from a user.

In order to prevent tracking duplicate activities each userId, activityId, and occurrence when combined should be unique.

Use this method, if there are no plans to track activities in batches. Otherwise, tracking activities in batches is preferred for efficiency and to reduce load on our systems.

Params

export interface TrackActivityInput {
    occurrence: string;
    count?: number;
    activityId: string;
    userId: string;
}

occurrence is the datetime of when this event occurred in ISO format. Example: 2024-04-20T18:18:03.369Z

count is the number of times this event happened. Default is 1.

activityId is similar to an analytics tracking event name which is used to identify activities with their quests.

userId is the same userId used to register this user.

Return Type

export interface TrackActivity200Response {
  message: string;
  data: {
    activityId: string;
    userId: string;
    count: number;
    occurence: Date;
    processed: boolean;
  } | null;
}

message indicating activity has been successfully recorded and has been queued for processing.

data is null if no activity was tracked. Otherwise, returns tracked activity data.

Description

Track an array of game activities (events) for a given user ID.

This method is similar to trackActivity, but it allows tracking multiple activities in a single request.

Params

userId: string

export interface TrackBatchActivitiesInput = {
  activityId: string;
  count?: number;
  occurrence: string;
}[];

See trackActivity for details about params.

Return Type

export interface TrackBatchActivitiesByUser200Response {
    'count': number;
    'message': string;
}

count indicating the number of succesfully inserted activities.

message indicating activity has been successfully recorded and has been queued for processing.

Ledge Client Error Types

ApiError

| Property | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | code | Ledge Specific status code which follows HTTP response status codes for the most part. | | message | Error message associated with this error code |

Error Codes

403 Invalid Api Key. Please reach out to Ledge.

400 Bad Request (e.g missing data, invalid inputs).

409 Conflict: User not registered, skipping this user. Make sure this user is registered with the ledge via registerUser

500 Internal Server Error.