Appearance

Using the SDK ​

Use the SDK to integrate Stack into your app in minutes. The SDK is available in Typescript and Javascript.

Get Started ​

Get your API key ​

Sign up at stack.so/signup to get your API key and create a point system. You can continue to track your point system in the Stack dashboard.

Install ​

Add the SDK to your project.

bash
npm install @stackso/js-core

Initialize the client ​

Use the StackClient to initialize the client, providing your API key and point system id from the Stack dashboard.

typescript
import { StackClient } from "@stackso/js-core";

// Initialize the client
const stack = new StackClient({
  // Get your API key and point system id from the Stack dashboard (stack.so)
  apiKey: "YOUR_API_KEY", 
  pointSystemId: "YOUR_POINT_SYSTEM_ID",
});

Add points and tag the event ​

Tagging each point assignment with an event name is important for tracking and analytics.

typescript
await stack.track("user_signup", {
  points: 10,
  account: "0x627306090abaB3A6e1400e9345bC60c78a8BEf57"
});

await stack.track("user_signup", {
  points: 15,
  account: "0x2eeb301387D6BDa23E02fa0c7463507c68b597B5",
});

Get events ​

Get the events for a specific event name using the getEvents method.

As of v0.4.2, getEvents() accepts a query parameter. Note: the default number of events to query is 100.

typescript
import { getAddress } from "viem";

await stack.getEvents({
  query: stack.eventsQuery()
    .where({
      eventType: "user_signup",
      associatedAccount: getAddress("0x2eeb301387D6BDa23E02fa0c7463507c68b597B5"),
      eventTimestamp: {
        gte: new Date("2024-03-23").toISOString(),
      }
    })
    .limit(1)
    .offset(0)
    .build()
});

// Returns an array of events
// => [
//   {
//     event: 'user_signup',
//     address: '0x2eeb301387D6BDa23E02fa0c7463507c68b597B5',
//     timestamp: '2024-03-23T16:14:24.898Z',
//     points: 15,
//     metadata: {}
//   }
// ]

Get event metrics ​

Get metrics across all events using getEventMetrics.

typescript
await stack.getEventMetrics({
  query: stack.eventsQuery()
    .where({
      eventType: "user_signup",
    })
    .build()
});

// Returns event metrics
// => {
//     totalEvents: 2, # total events
//     distinctEvents: 1, # number of different eventTypes
//   }
typescript
await stack.track("user_connected_wallet", {
  account: "0x627306090abaB3A6e1400e9345bC60c78a8BEf57",
  points: 30,
});

await stack.getEventMetrics({
  query: stack.eventsQuery()
    .where({
      account: "0x627306090abaB3A6e1400e9345bC60c78a8BEf57"
    })
    .build()
});

// Returns event metrics
// => {
//     totalEvents: 2, 
//     distinctEvents: 2, // "user_connected_wallet", "user_signup"
//   }

Fetching points for user ​

Get the points for an account using the getPoints method, providing the account address.

typescript
await stack.getPoints("0x627306090abaB3A6e1400e9345bC60c78a8BEf57");
// => 10

Parameters ​

  • account: The Ethereum address for which you want to get the points.

Returns ​

  • number: The total points for the account.

Fetching points for list of users ​

You can also use getPoints with an array. Simply pass an array of account addresses to get the points for multiple accounts.

typescript
await stack.getPoints([
  "0x627306090abaB3A6e1400e9345bC60c78a8BEf57",
  "0x2eeb301387D6BDa23E02fa0c7463507c68b597B5"
]);

// => [
//   {account: "0x627306090abaB3A6e1400e9345bC60c78a8BEf57", points: 10},
//   {account: "0x2eeb301387D6BDa23E02fa0c7463507c68b597B5", points: 15}
// ]

Fetching points by eventType ​

You can also filter by eventType when fetching points.

typescript
await stack.getPoints([
  "0x627306090abaB3A6e1400e9345bC60c78a8BEf57",
  "0x2eeb301387D6BDa23E02fa0c7463507c68b597B5"
], { event: "user_signup" });

// => [
//   {account: "0x627306090abaB3A6e1400e9345bC60c78a8BEf57", points: 10},
//   {account: "0x2eeb301387D6BDa23E02fa0c7463507c68b597B5", points: 15}
// ]

Handling duplicate events ​

The SDK provides a parameter uniqueId that uniquely identifies an event type for your point system and will only track the first event we receive with this uniqueId.

typescript
// sending this "user_first_referral" event twice will result in only
// the first one being processed
await stack.track("user_first_referral", {
  points: 15,
  account: "0x2eeb301387D6BDa23E02fa0c7463507c68b597B5",
  uniqueId: "0x2eeb301387D6BDa23E02fa0c7463507c68b597B5",
});

Some ideas for uniqueId include:

A unique identifier in your system ​

For example, a userId that is associated with multiple EOAs that you want to prevent from being double counted.

typescript
// Sending this "user_first_referral" event twice will result in only
// the first one being processed.
await stack.track("user_first_referral", {
  points: 15,
  account: "0x2eeb301387D6BDa23E02fa0c7463507c68b597B5",
  uniqueId: "2540-4a99-83c2-3d7f", // a unique userId in your system
});

A unique timeframe ​

For a wallet you only want to log at most 1 event per day, using a date string in the uniqueId (e.g. 2024-04-01) – will prevent the same event from being logged more than once per day.

typescript
await stack.track("DailyWalletLogin", {
  points: 15,
  account: "0x2eeb301387D6BDa23E02fa0c7463507c68b597B5",
  uniqueId: `${(new Date()).toISOString().split('T')[0]}-0x2eeb301387D6BDa23E02fa0c7463507c68b597B5`,
});

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.
  • Consider using the uniqueId parameter to prevent duplicate events from being tracked, especially for critical actions.
  • Regularly monitor your point system in the Stack dashboard to ensure accurate tracking and make any necessary adjustments.