Skip to main content

Set up your environment

Estimated time to complete: 15 minutes

Before you begin your Immutable integration, you will need to set up your environment correctly.

Sections
setting up your environmentsetting up your environment

Task 1: Join Immutable Hub​

Immutable Hub is the admin panel and learning platform for Immutable developers. Sign up typically takes between 3 and 5 minutes and you’ll be asked 8 simple questions to help us understand what you’re building.

Immutable Hub

Task 2: Use Hub to create a zkEVM project​

Once you’ve set up your Hub account, you can create a project. Create a project and fill in the following in the setup flow:

  • Project Name: the name of your application (e.g. My Project)
  • Project Rollup: Immutable zkEVM
  • Environment Name: anything you want (e.g. Testing)
  • Environment Type: Testnet

Games should initially build on our testing/testnet environment before switching to production/mainnet.

💡NOTE
Immutable zkEVM Mainnet will be launched in Q1 of 2024. All projects should begin building on testnet initially, and releasing into production will require only a simple configuration change.

Once complete, you should see the Project screen inside Immutable Hub, where you'll configure your Immutable integration for this project. Consider keeping the browser tab open so you can easily return to it later.

New Hub Project

Task 3: Create Publishable and Secret API Keys​

Once you've set up your project and environment, the next step is to create a Publishable and Secret API key under the environment you just created. You'll use these in the next step when you install and configure the Immutable Typescript SDK. You can learn more about our APIs and API keys.

You can create and manage your keys in the API Keys tab in an environment. Consider keeping this tab open to easily copy the keys when initialising and configuring the Immutable Typescript SDK.

API Key Management

Task 4: Install the Immutable SDK​

💡NOTE
This tutorial uses the Immutable Typescript SDK. We will soon add our Unity and Unreal Engine SDKs to this tutorial.

Prerequisites​

Node Version >18
Immutable's Typescript SDK requires **Node v18** (Active LTS version) or **higher**. Node v18 can be installed via `nvm`.

To install nvm follow these instructions. Once installed, run:

nvm install --lts
  • (Optional) To enable code splitting (importing only the SDK modules you need) there are additional prerequisites. See the Code Splitting section below.

Install the Immutable SDK​

Run the following command in your project root directory.

npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node
Troubleshooting

The Immutable SDK is still in early development. If experiencing complications, use the following commands to ensure the most recent release of the SDK is correctly installed:

rm -Rf node_modules
npm cache clean --force
npm i

How to use API Keys​

Using the Publishable Key​

What is the Publishable Key for?
Publishable Keys are used to identify your integration for tracking and analytics purposes. It's not a secret key and is safe for client-side applications, like web browsers, mobile applications and game clients as it is designed to be publicly safe and anonymous.
const baseConfig = {
  environment: config.Environment.PRODUCTION,
  publishableKey: YOUR_PUBLISHABLE_KEY, // Replace with your Publishable Key from the Immutable Hub
};
curl --request GET \
  --url https://api.sandbox.immutable.com/v1/chains/imtbl-zkevm-testnet/collections \
  -H 'Content-Type: application/json' \
  -H 'x-immutable-publishable-key: [YOUR_PUBLISHABLE_KEY]'

Using the Secret API Key​

What is the Secret API Key for?
Secret API Keys are used to authenticate and authorise your backend integrations with Immutable. Don’t expose this key on a website or embed it in a game client or mobile application.
import { config, blockchainData } from '@imtbl/sdk';

const client = new blockchainData.BlockchainData({
  baseConfig: {
    environment: config.Environment.PRODUCTION,
    apiKey: YOUR_SECRET_API_KEY,
    publishableKey: YOUR_PUBLISHABLE_KEY,
  },
});
curl --request POST \
  --url https://api.sandbox.immutable.com/v1/chains/imtbl-zkevm-testnet/collections/0x8a90cab2b38dba80c64b7734e58ee1db38b8992e/refresh-metadata \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-immutable-api-key: [YOUR_SECRET_API_KEY]' \
  --data '{
  "collection_metadata": {
    "name": "Gigantic Lizards",
    "symbol": "GLZ",
    "description": "This is the Gigantic Lizards collection",
    "image": "https://some-url",
    "external_link": "https://some-url",
    "contract_uri": "https://some-url",
    "base_uri": "https://some-url"
  }
}'