@xsolla/metaframe-react-sdk v1.8.2

Metaframe React SDK

SDK for connecting your Website with a Metaframe

Allows users to see their orbs amount, wallet, backpack, and more.

Prerequisites

This project requires NodeJS (version 16 or later) and React (version 17 or later).

Deprecated SDK

@xsolla/babka-overlay-sdk

If you want to use Metaframe with any React project use here

If you want to use Metaframe with any JS project use version 1.7.0 and refer to the documentation in the README-OLD.md file here

Installation

Install with your package manager of choice.

npm install @xsolla/metaframe-react-sdk

yarn add @xsolla/metaframe-react-sdk

pnpm install @xsolla/metaframe-react-sdk

Configuration

Metaframe accepts the following params.

loginProjectId (required)

Type: string
The Login Project ID with which Babka authorization will be performed.

onLogin (optional)

Type: (token: string) => void
The callback that called after successful login in Metaframe.

onLogout (required)

Type: () => void
The callback that called after logout from Metaframe.

locale (optional)

Type: string
Language abbreviation (ISO 631 1), dash (-) and country abbreviation (ISO 3166 1).

Supported locales: "en_US", "de_DE", "es_ES", "ja_JP", "ko_KR", "pt_PT", "ru_RU", "cn_CN"

Example: "Locale.en_US"
If not provided will be the "en_US" locale.

shortcutKeys (optional)

Type: string[]
Combination of key codes to be used as shortcut to trigger Metaframe.

Example: "ShiftLeft", "Tab"
If shortcutKeys is not provided, the shortcut will be disabled by default.

enabledOrbs (optional)

Type: string[] Orbs to be enabled in the Metaframe.

Supported orbs: "blue", "gold"

Example: "blue", "gold" If enabledOrbs is not specified, all orbs will be enabled by default.

googleAnalyticsId (optional)

Type: string Google Analytics ID to track events in Metaframe for analytics. For the list of all events available for analytics, please refer to the Events section

Example: "G-DMCP19DPQM"

telemetry (optional)

Type: boolean Enabling telemetry means that you are allowing Xsolla to automatically collects, transmits and measures data from Metaframe to improve Metaframe in the future.

Telemetry is defaulted to true. To disable telemetry, please set telemetry to false.

Usage

Basic usage

Use Metaframe component in your React project

import React from "react";
import { Metaframe, Locale } from "@xsolla/metaframe-react-sdk";

export const App = () => {
  return (
    <Metaframe
      loginProjectId="your-login-project-id"
      locale={Locale.en_US}
      shortcutKeys={["ShiftLeft", "Tab"]}
    />
    // other application/component code
  );
};

With this Metaframe will display all available pages in this order if token in xsolla_metaframe_token cookie is valid: Wallet, Keychain, Backpack, Orbs, Profile. If token isn't valid Metaframe will display Login page.

Custom usage

Use Metaframe as a wrapper. You can change order of the pages, remove default pages and add custom pages.

import React from "react";
import {
  Metaframe,
  Wallet,
  Orbs,
  Profile,
  Locale,
} from "@xsolla/metaframe-react-sdk";

import { CustomComponent } from "./components";

export const App = () => {
  return (
    <Metaframe
      loginProjectId="your-login-project-id"
      locale={Locale.en_US}
      shortcutKeys={["ShiftLeft", "Tab"]}
    >
      <CustomComponent />
      <Orbs />
      <Wallet />
      <Profile />
    </Metaframe>
    // your application/component code
  );
};

Available pages: <Wallet />, <Orbs />, <Profile />, <Backpack />, <Keychain />

Utils

Events

Listen to events in your React project

import React, { useEffect } from "react";
import { Metaframe, Locale, MetaframeEvent } from "@xsolla/metaframe-react-sdk";

export const App = () => {
  useEffect(() => {
    MetaframeEvent.on("metaframe.resize", ({ width, height }) => {
      console.log("width", width);
      // Write your callback function here
    });
  }, []);

  return (
    <Metaframe
      token="user-token-value"
      locale={Locale.en_US}
      shortcutKeys={["ShiftLeft", "Tab"]}
    />
  );
};