Sportstalk 247 Javascript SDK

My using this SDK you agree to the license located in LICENSE.md

STATUS: STABLE BETA This SDK is used in production successfully and is considered stable. At the same time, the SDK is under active development and improvement. We are also very open to feedback if you experience pain points while using the SDK.

GETTING STARTED: Setting up the SDK

Install via NPM

npm install sportstalk-sdk --save

App Id and api Tokens

Clients and services require a SportsTalkConfig object, which looks like so:

{
    appId: 'yourappID-from-the-dashboard',
    apiToken: 'yourApiToken-from-the-dashboard', // NOTE: you should use a proxy to hide your token and restrict behavior to specific domains on the web.
    endpoint: 'custom-endpoint' // OPTIONAL Use this to set a proxy on the web, or if you have an on-prem install of sportstalk at a custom location.
}

If you are using a proxy, the only mandatory data for a SportstalkConfig object is the appId and endpoint. Otherwise you will need to provide the appId and apiToken

Using the SDK on the Web

To use directly, we host the web SDK on our website.

You can also look inside the Sportstalk package at /dist/web-sdk.js or use the minified version at /dist/web-sdk.min.js

Source Documentation

The Sportstalk SDK is open source with substantial comments. You can see everything here: https://gitlab.com/sportstalk247/sdk-javascript/-/tree/master/src

Creating Client Objects

Using require

You can use require as well.

const sdk = require('sportstalk-sdk');
const commentClient = sdk.CommentClient.init({appId..., apiToken...});
const chatClient = sdk.ChatClient.init(({appId..., apiToken...});

You will need to register with SportsTalk and get an API Key in order to use sportstalk functions.

A Note on Promises

Almost all SDK functions require communication with a server. Therefore, most methods will return a Promise. Promises are very common but you need to be familiar with them to use the SportStalk SDK.

Here are some ways that you can use promises.

commentsClient.listConversations()
    .then(function(response) {
      const conversations = response.conversations;
      // handle UI functions here.
    }).catch(function(e){
      // catch an error and handle it here.
    })

You can also use comments in async/await blocks (preferred).

async function yourFunction() {
    const response = await commentsClient.listConversations();
    const conversations = response.conversations;
    // handle ui using conversations here.
}

For more reading, please see this article: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise

A note on Typescript

The SDK is written in Typescript which provides type checking and the ability to declare and describe objects similar to typed languages such as Java. This is very helpful when describing parameters or models because you can reference all the possible members of an object ahead of time.

You do not need to write your project in typescript to use this SDK. This SDK provides full JS compatibility and most examples are shown in standard JS (Node). However, understanding basic typescript notation is still helpful for understanding the data models returned by the API.

There is a 5 min primer on typescript and you can get started with typescript here: https://www.typescriptlang.org/docs/home.html

Understanding the SDK

Key concepts

CHAT: This is a real-time experience designed to make a user feel like other people are present with that person. The state of a chat room updates in real time, and you receive notifications that update the state. In general, chat content is disposable: It is enjoyed in the moment but in the future its rare for people to go back and look at past conversation information. Chat messages are also often short and don’t necessarily add a thought to the conversation. Chat drives engagement in the moment by keeping your attention and is best used with live events because its no fun to be in a chat room by yourself.

ROOM: A chat “room” is a virtual space in which people can chat. Events occur in the room, such as a person entering the room, saying something, or exiting the room. If a user reacts to something by liking it, this also generates an event. The SDK listens for new events, processes events, raises call backs for you, and updates the state of the room in memory, so it’s less work for the developer.

COMMENTS: A comment is something you post on an article or video or other context. Unlike chat, comments are often read long after they are posted, and are more likely to be longer messages that contain a more thoughtful point. They are intended to add to the value of the thing on which the comment appears. Use comments when you don’t real time responses, people will see your comment later.

CONVERSATION: This is a commenting context, such as an article or video that people are commenting on. Comments are created within the context of a conversation.

Chats belong to Rooms and Comments belong in Conversations

Client Objects

The SDK is broken up into 2 Clients and a set of backing services. For most user-facing operations you’ll want one of the clients:

const chatClient = require('sportstalk-sdk').ChatClient.init({appId, apiToken});
const commentClient = require('sportstalk-sdk').CommentClient.init({appId, apiToken});

These clients handle most common operation while hiding the backing APIs and simplifying some operations and will manage state for you.

However, you may want to use the APIs directly, in which case there are a set of backing REST services that you can use: