@xsolla/metaframe-react-sdk v1.9.0

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.

merchantId (required if enabledV2 enabled)

Type: number
The Merchant ID in Publisher Account.

projectId (required if enabledV2 enabled)

Type: number
The Project ID in Publisher Account.

hostId (required if enabledV2 enabled)

Type: string
Reference: How to get hostId.

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

For now Metaframe support only english language

Supported locales: "en_US"

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"

autoLoginPopup (optional)

Type: boolean Default: false

Enabling auto login popup show initially.

theme (optional)

Type: Theme.Dark | Theme.Light Default: Theme.Dark

Change the Metaframe theme

mobileLayout (optional)

Type: string Default: bottom Supported values: "horizontal", "vertical", "bottom"

Allows you to set the position of the widget on a mobile device.

isOnlyMenu (optional)

Type: boolean Default: false Leaves in the widget only button to open menu in mobile layout.

customPageHeightBehavior (optional)

Type: string Default: fixed Supported values: "fixed", "fit-content"

Defines custom page's height behavior on non-mobile resolutions.

enabledV2 (optional)

Enabling V2 - Multicurrencies. (Note: If enabled, merchantId, projectId, apiKey, hostId are required.)

Usage

Basic usage

Use Metaframe component in your React project

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

export const App = () => {
  return (
    <Metaframe
      loginProjectId="your-login-project-id"
      locale={Locale.en_US}
      shortcutKeys={["ShiftLeft", "Tab"]}
      merchantId={merchantId}
      projectId={projectId}
      hostId="your-host-id"
      enabledV2
      theme={Theme.Dark}
    />
    // 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. Wrap your CustomComponent in a CustomNavItem to work correctly.

import React from "react";
import {
  Metaframe,
  Wallet,
  Orbs,
  Profile,
  Locale,
  CustomNavItem,
  FullScreenMenuPage,
} 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"]}
      merchantId={merchantId}
      projectId={projectId}
      hostId="your-host-id"
      enabledV2
    >
      <CustomNavItem onClick={customEvent} pageName="customName">
        <CustomComponent />
      </CustomNavItem>
      <Orbs />
      <Wallet />
      <Profile />
    </Metaframe>
    // your application/component code
  );
};

Available pages: <Wallet />, <Orbs />, <Profile />, <Backpack />, <Keychain /> Additional button: <FullScreenMenuPage /> - to open menu in full screen on mobile layout.

Example use CustomPage. If you want open CustomPage, using CustomNavItem with handler openCustomPage as in the example. CustomPage working only mobile layout.

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

import { CustomComponent, CustomContent } from "./components";

export const App = () => {
  const customName = "customName";

  return (
    <Metaframe
      loginProjectId="your-login-project-id"
      locale={Locale.en_US}
      shortcutKeys={["ShiftLeft", "Tab"]}
      merchantId={merchantId}
      projectId={projectId}
      apiKey="your-api-key"
      hostId="your-host-id"
    >
      <CustomNavItem
        onClick={openCustomPage({ page: customName })}
        pageName={customName}
      >
        <CustomComponent />
      </CustomNavItem>
      <CustomPage pageName={customName}>
        <CustomContent />
      </CustomPage>
      <Orbs />
      <Wallet />
      <Profile />
    </Metaframe>
    // your application/component code
  );
};

Note: For the time being, the use Orbs of the mobile layout in vertical is not possible

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"]}
      merchantId={merchantId}
      projectId={projectId}
      hostId="your-host-id"
      enabledV2
    />
  );
};