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:
- When
idSchema
is NOT provided. Logs the following message:
If no idSchema is passed the default one will be set which is: native. - 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. - When
environment
is NOT provided. Logs the following message:
If no environment is passed the default one will be set which is: prod. - 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. - When
lang
is NOT provided. Logs the following message:
If no lang is passed the default one will be set which is: en. - 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. - When
errorHandlingMode
is NOT provided. Logs the following message:
If no errorHandlingMode is passed the default one will be set which is: default. - 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. - When for
authProvider
field has been provided more properties than the expected ones (getIdToken
andlogout
):
You have passed a property which is not supported for the authentication provider: - 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. - 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:
- When
apiKey
is NOT provided. Throws the following message:
The field apiKey with valid value must be provided to use Fans United JS SDK. - When
clientId
is NOT provided. Throws the following message:
The field clientId must be provided to use Fans United JS SDK. - 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:. - When
authProvider
is NOT provided. Throws the following message:
The field authProvider must be provided to use this SDK. - When
authProvider
is missing some ofFansUnitedAuthInterface
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
}
Updated 8 days ago