JavaScript SDK

Overview of the JavaScript SDK for Fans United platform

Welcome to the Fans United JavaScript SDK. This SDK works for client-side, server-side and React Native implementations.
The SDK has complete coverage of the Fans United APIs and is split into different namespaces depending on what you want to achieve.

Operations supported by the SDK:

  • Profile Operations
  • Football Operations
  • Predictor Operations
  • Top X Operations
  • Match Quiz Operations
  • Loyalty Operations
  • Activity Operations
  • Mini-Games Operations
  • Progress Operations
  • Private Leagues Operations
  • Discussions Operations
  • Fantasy Operations
  • Voting Operations
  • Odds Operations
  • Bracket Games Operations
  • Challenges Operations
  • Helpers Operations
  • Lists Operations
  • Standing Games operations

Install the SDK

The JavaScript SDK is distributed as 2 NPM packages - ESM and UMD.

ESM

Install JavaScript SDK as ESM dependency by running the following command:

npm i fansunited-sdk-esm
yarn add fansunited-sdk-esm

UMD

For UMD package run the following command:

npm i fansunited-sdk-umd
yarn add fansunited-sdk-umd

For CDN add the following script command in your html file:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/index.js"></script>

Where "@1.23.0" is the version of JS SDK that you want to use in your application.

Use the SDK in your app

The SDK works with JWTs provided from OAuth2 provider. The default provider is Firebase Authentication, but if the
client has their own provider, it can be integrated into the platform.

The SDK comes with a configuration and an interface. The client needs to implement this interface and pass the implementation in the config.

Initiate the SDK

This is what the SDK config requires:

N.B: The following example is when JavaScript SDK is installed as an ESM dependency

import {FansUnitedSDK} from "fansunited-sdk-esm";

let fansUnitedSdk = FansUnitedSDK({
    apiKey: "your-api-key-here",
    environment: "prod|watg|yolo", // default: prod
    clientId: "your-client-id-here",
    lang: "bg|en|ro|el|sk", // default: en
    idSchema: "native|enetpulse|sportradar|sportal365", // default: native
    errorHandlingMode: "default|standard", // default: default
    oddClient: "oddClient", // Define your odd client here. When not provided, the Odds namespace will NOT work
  	cookieToken: {
      name: "nameOfTheCookie",
      requestHeaders: Headers, // Fetch API Headers. Optional, but will be required in server-side
    }, // optional
    authProvider: new myTokenProvider() //Optional, but it will be required if cookieToken not provided
});

You need to create a class that has the following 2 methods:

  • getIdToken() - This function should return a valid JWT as a string. This token is used for all requests that require authentication. If any API returns 401 Unauthorized response, the SDK will repeat the request by calling the getIdToken() function again, expecting that the token has been changed. If the token has not changed and the API still returns 401, the exception will be relayed to the client.
  • logout() - you can implement custom logout logic here

A client supplied class would look like this:

class myTokenProvider {
  getIdToken = () => {
    // custom logic ....
    return "tokenString"; // no need prefixing this with Bearer. Just the plain token string is needed
  }
  logout = () => {
    // custom logic ....
  };
}

TypeScript

Providing configuration to JS SDK in TypeScript projects follow this model:

class SDKConfigurationModel {
    apiKey: string;
    clientId: string;
    environment?: EnvironmentType;
    idSchema?: IdSchemaType;
    lang?: LangType;
  	errorHandlingMode?: ErrorHandlingModeType;
    oddClient?: string;
  	cookieToken?: CookieTokenType;
    authProvider?: FansUnitedAuthInterface;
}

type EnvironmentType = 'dev' | 'prod' | 'staging' | 'watg' | 'yolo';
type IdSchemaType = 'native' | 'enetpulse' | 'sportal365' | 'sportradar';
type LangType = 'bg' | 'en' | 'ro' | 'el' | 'sk';
type ErrorHandlingModeType = 'default' | 'standard';
type CookieTokenType = {
  name: string;
  requestHeaders?: Headers;
};

Here is an example how you can construct this configuration:

class TokenProvider {
	public getIdToken = (): string => {
    // custom logic ....
    return "tokenString";
	};
	public logout = () => {
  	// custom logic ....
  };
}

const idSchema: IdSchemaType = 'sportal365';
const lang: LangType = 'bg';
const environment: EnvironmentType = 'staging';
const errorHandlingMode: ErrorHandlingModeType = 'standard';
const oddClient = "oddClient";
const cookieToken = {
  name: "nameOfTheCookie",
  headers: Headers
};

const config = {
  apiKey: "AIzaSyBDsY25nJ4VZz0iiLLQpPRnjMRnIHkyqg4",
  clientId: "productiontesting1",
  authProvider: new TokenProvider(),
  cookieToken, // Optional, if not provided authProvider will be required
  idSchema,
  lang,
  environment,
  errorHandlingMode,
  oddClient
};

N.B
As you can see from SDKConfigurationModel, fields idSchema, lang, environment , errorHandlingMode, oddClient, cookieToken and authProvider are optional. If they are not provided, they will be set to default values (except for oddClient, cookieToken and authProvider). Default values: idSchema: "native", lang: "en", environment: "prod", errorHandlingMode: "default".

When no oddClient is provided, the Odds namespace can't be used

When cookieToken is not provided, then authProvider will be required

Configuration validator

When you provide a configuration, it gets validate before Fans United JS SDK initialisation. If some of the fields are missing or invalid, warning messages are logged or error messages are throwed.

Warning messages

All warning messages are logged to the developer. The following cases contains warning messages:

  1. When idSchema is NOT provided. Logs the following message:
    If no idSchema is passed the default one will be set which is: native.
  2. When idSchema is provided, but the value is NOT supported:
    This idSchema value is not supported, the default one will be set which is: native.
  3. When environment is NOT provided. Logs the following message:
    If no environment is passed the default one will be set which is: prod.
  4. When environment is provided, but the value is NOT supported:
    This environment value is not supported, the default one will be set which is: prod.
  5. When lang is NOT provided. Logs the following message:
    If no lang is passed the default one will be set which is: en.
  6. When lang is provided, but the value is NOT supported:
    This lang value is not supported, the default one will be set which is: en.
  7. When errorHandlingMode is NOT provided. Logs the following message:
    If no errorHandlingMode is passed the default one will be set which is: default.
  8. When errorHandlingMode is provided, but the value is NOT supported:
    This errorHandlingMode value is not supported, the default one will be set which is: default.
  9. When for authProvider field has been provided more properties than the expected ones (getIdToken and logout):
    You have passed a property which is not supported for the authentication provider:
  10. When oddClient is NOT provided logs the following message:
    If no oddClient is passed the Odds namespace will not work. For more information check our documentation.
  11. When cookieToken consist properties who are not supported logs the following message:
    The following property is missing from the cookieToken object:.

Error messages

All error messages are throwed to the developer. The following cases contains error messages:

  1. When apiKey is NOT provided. Throws the following message:
    The field apiKey with valid value must be provided to use Fans United JS SDK.
  2. When clientId is NOT provided. Throws the following message:
    The field clientId must be provided to use Fans United JS SDK.
  3. When cookieToken is missing some of if properties logs the following message:
    You have passed properties which are not supported for the cookie token configuration property:.
  4. When authProvider is NOT provided. Throws the following message:
    The field authProvider must be provided to use this SDK.
  5. When authProvider is missing some of FansUnitedAuthInterface methods. Throws the following message:
    The following property is missing from the authProvider object:

SDK instance versioning

getVersion method

To be able to see the current version of SDK that you are using, you can call the getVersion method. It returns the following method:

📘

Method call:

const version = sdk.getVersion();
console.log(version) // See below for logged model

The version as it follows:

{
   version: "1.78.0",
   major: 1,
   minor: 78,
   patch: 0,
   releaseCandidate: null, // When version is 1.78.0-RC1, then the releaseCandidate will be 1
}