Intended Audience

Software developers or those with technical knowledge.

Included with this guide

• API keys for both testing and production environments

• API URLs

  • testing: https://staging-external-api.ledge.io

  • production: https://external-api.ledge.io

• API docs

  • testing

  • production

• Ledge Typescript SDK

  • if a different SDK is needed, please contact the Ledge

• Event quests details with activity ids

  • If you haven’t received these details yet, please contact the Ledge

SDK Integration Overview

For detailed SDK integration instructions, please see the Ledge Typescript SDK repository.

Registering a User

In step 3, we register a user with the arguments:

1. User id a unique string used to identify the user on the Ledge as well as tracking which activities belongs to this user.

2. Username is string displayed on the event leaderboard, if it exists.

3. Original creation date is optional and used for attribution purposes. This is the date when this user first signed up on your platform.

Once a user is registered, the endpoint returns a response, see Understanding the User Registration Flow.

Tracking In-Game User Activity

In step 4, we track a single user activity. However, it might make more sense for you to track user activities in batches, see trackBatchActivitiesByUser. In any case, both endpoints take the following arguments:

1. User id is the same id used when registering this user.

2. Activity ids (strings) are found with the quest designs. Each quest has an associated activity id, so we know which quest this activity should be applied to.

3. Count (integer) is the number of times this activity was performed. For example, if the quest is ‘Kill 5 Zombies’ and the count is 2, then we know 2 zombies were killed.

4. Occurrence is a date time when combined with activity id is used to prevent duplicate activities from being tracked. This can be the date time at which this game match ended or the time when this specific activity was performed.

Once a user’s activity is sent, we record this data and begin processing it, so that users get progress towards this event’s quests. See Understanding the User Activity Tracking Flow.

Understanding the User Registration Flow

After you’ve integrated our SDK and called registerUser, a Ledge URL and code is returned. See the example returned response below.

{
  "ledgeLink": "https://app.ledge.io/?linkingCode=HJKADQ&gameId=your-game,
  "linkingCode": "HJKADQ"
}

When the user opens you’re game, they should see a Ledge button. When this button is clicked, it opens the Ledge website and prompts the user to login/sign up. See login and onboarding flow for more details.

Once the user has completed the login and onboarding flow, a game connection pop up will appear. See game connection for more details.

This means you’ll need to return the Ledge URL to your client so that when the user clicks on the Ledge button, it will open the Ledge web application.

After the user has successfully linked their account, we can begin tracking their in game activity. By design, any previously received activity will not be retroactively applied to previous nor current quests.

Understanding the User Activity Tracking Flow

When you call any track activity endpoint, we record this in our database for future processing. Processing means to give this user progress towards quests and/or leaderboard score, if this user qualifies.

Processing is based on the user id and activity id parameters. The activity id is very important as it dictates which quest this tracked activity will count towards.

This means you may need to map certain values to the appropriate activity id (provided by Ledge) when calling our track activity endpoint(s).

Depending on the activity id, the user’s progress towards a quest or leaderboard will be updated cumulatively (summed) or milestoned (the highest value). We handle updating the user’s progress on our end, so you don’t need to worry about whether the quest is cumulative or milestone based.

When processing is complete, the user should see the changes reflect on the Ledge web application immediately.

Once a quest is complete, the user receives a reward (e.g a ledge raffle ticket) depending on the quest completed.

Post Event - Off boarding

By default API keys will be disabled after 2 weeks. We can extend this indefinitely if needed.

FAQ

If a user is not yet registered with Ledge, is there activity still tracked?Yes, their activity is still tracked (recorded in our database) but the user does not receive progress towards any quest because we have no way of knowing which user this activity data belongs too until they’ve linked their accounts via the game connection flow.

What is the occurrence parameter when tracking activities?Occurrence is the date time at which this user performed this activity. It is used to prevent duplicate data from being tracked and processed.Example: after a game match, you call track activity with occurrence 2024-08-07T01:27:00.822Z and activityId io.ledge:kill-zombies:cumulative. If you try calling the same method with the same occurrence and activityId arguments, our endpoint will skip recording this in our database.