@blockedprotocol/points-sdk
v0.0.4
Published
# Using the SDK
Downloads
5
Readme
Blocked Points SDK
Using the SDK
Use the SDK to integrate Blocked Points SDK into your app in minutes. The SDK is available in Typescript and Javascript.
Best Practices
- Make sure to keep your API key secure and do not expose it in client-side code.
- Use meaningful event names that clearly describe the action being performed.
- Use a maximum of 4 digits after the decimal point for your points.
Get Started
Get your API key
Contact Blocked Protocol team to receive your private keys
Installation
npm add @blockedprotocol/points-sdk
Initialize the client
Use the newBlockedSdk
method to initialize the client, providing your API key and point system id.
import { newBlockedSdk } from "@blockedprotocol/points-sdk";
const blockedSdk = newBlockedSdk({
apiKey: "YOUR_API_KEY",
pointsSystemId: "YOUR_POINT_SYSTEM_ID",
});
By default it'll use production environment, but you can pass env: "development"
to use development environment.
Add points and tag the event
Tagging each point assignment with an event name is important for tracking and analytics.
await blockedSdk.points.track("login", {
points: 100,
account: "11111111111111111111111111111111",
});
await blockedSdk.points.track("transfer_eth_cosmos", {
points: 515,
account: "22222222222222222222222222222222",
});
Substract points
You can substract points for account using the negative value. The following example will decrement 50 points:
await blockedSdk.points.track("penalty", {
points: -50,
account: "11111111111111111111111111111111",
});
Multiply points
You can multiply points. The following example will multiply points by 1.5:
await blockedSdk.points.track("top_user", {
account: "11111111111111111111111111111111",
multiplicator: 1.5,
});
Get points for an account
Get the points for an account using the getPoints method, providing the account address.
await blockedSdk.points.getPoints("11111111111111111111111111111111");
// => { points: 100 }
Get leaderboard
Get the leaderboard using the getLeaderboard method. The response defaults to the top 100 users. Pagination support coming soon
await blockedSdk.points.getLeaderboard();
// => [
// { account: "11111111111111111111111111111111", points: 100 },
// { account: "22222222222222222222222222222222", points: 515 }
// ]
Get Leaderboard Rank
Get the rank of an account in the leaderboard using the getLeaderboardRank method.
await blockedSdk.points.getLeaderboardRank("11111111111111111111111111111111");
// {
// account: '11111111111111111111111111111111',
// rank: 1,
// points: 100
// }
Get events
Get the events for a specific event name using the getEvents method.
await blockedSdk.points.getEvents({
account: "11111111111111111111111111111111", // filter by address
event: "login", // filter by event name
});
// Returns an array of events
// => [
// {
// event: 'login',
// account: '11111111111111111111111111111111',
// timestamp: 1712326918956,
// points: 100,
// }
// ]
If you don't specify the event
field, it'll return all events for a given account
Create User
User
- is an entity allows to link multiple accounts and utilize referral system
Here's how you can create user:
await blockedSdk.users.create(["11111111111111111111111111111111"]);
// => { id: "<USER_ID>" }
Note: if account already linked to another user, error will be thrown.
Create user with referrer
If you know that account A
has referred account B
, you can create a user entity and provide the referral information.
Follow the code snippet to create user and specify referrer:
// 1. find referrer user
// if user doesn't exist for account, error will be thrown
// see step above on how to create user without referrer
const referrerUser = blockedSdk.users.findByAccount("A");
// 2. create user
await blockedSdk.users.create(["B"], referrerUser.id);
// => { id: "<USER_ID>" }
As a result you craeted user B
referred by user A
.
Link multiple wallets to user
You can link accounts to a user even after user entity was created.
If you know that user with account abc
has also accounts aaa
and bbb
.
// 1. Find user with account `abc`
// if user doesn't exist for account, error will be thrown
// see step above on how to create user
const user = await blockedApi.users.findByAccount("abc");
// 2. Link accounts `aaa` and `bbb` to the same user
await blockedApi.users.linkAccounts(user.id, ["aaa", "bbb"]);
Get points for user
Returns cumulutive value for all accounts linked to user
const user = blockedSdk.users.findByAccount("11111111111111111111111111111111");
await blockedSdk.points.getPointsForUser(user.id);
// => { points: 100 }