Installing the Webplayer

1. Create a project and device using the Client API

The Corellium Webplayer Client requires a device to be created before it can be used. You can create a device using the Corellium Client API or CLI.

To create a device using the Corellium API, you must first install the package:

npm install @corellium/corellium-api

Then, create a new device and project using the following code:

const { Corellium } = require('@corellium/corellium-api');
​
const flavor = 'iphone6';
const os = '12.5.6';
const apiToken = 'my_api_token';
const endpoint = 'my_endpoint.enterprise.corellium.com';
const snapshot = 'my_snapshot_id';
​
const corellium = new Corellium({
  endpoint,
  apiToken,
});
​
const createProjectAndInstance = async () => {
  try {
    const project = await corellium.createProject('Webplayer Project');

    await project.setQuotas({ cores: 6 });
    
    const instance = await project.createInstance({
      name: 'Webplayer Device',
      flavor,
      os,
      bootOptions: {
        snapshot,
      },
    });
​
    console.log('project id :>>', project.id);
    console.log('instance id :>> ', instance.id); // also device id
  } catch (error) {
    console.error(error);
  }
};
​
createProjectAndInstance();

For each instance of a webplayer you should have one project containing one device. When you create a project, you'll notice you need to set a quota for the project. This is the number of cores that will be allocated to the project. You can set this to any number you like, but we recommend setting it to the number of cores needed for the device that runs. Common values will include 2 and 6.

2. Create an API Endpoint for Authentication

In order to use the Webplayer you will need to exchange your API token for a JWT. As this requires your API Token and other sensitive information, you should not expose this endpoint to the public. Instead, you should create a backend API endpoint that will handle this authentication for you.

const baseDomain = 'app.corellium.com';   // Your Corellium Domain
const apiToken = 'abcd1234';              // Your API token
const expiresIn = 18000;                  // Token expiration, in seconds (e.g. 18000 = 5 hours)

const handler = (req) => {
  const { projectId, instanceId, features } = req.body; // These will come from the frontend. See below.

  const response = await fetch(`https://${baseDomain}/api/v1/webplayer`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': apiToken,
    },
    body: JSON.stringify({
      projectId,
      instanceId,
      expiresIn,
      features,
    }),
  });

  const data = await response.json();

}

tip

Webplayer sessions are automatically renewed when the token expiry time drops below 15 minutes. As such, the minimum valid expiresIn value is 900.

3. Set up your HTML page

Your HTML should include an element to contain the Corellium iframe. An example is shown below.

When the iframe is loaded it will replace the contents of #corellium-webplayer with the Corellium Webplayer experience.

You can include code that handles loading and error conditions.

<div id="corellium-webplayer">
  <div id="corellium-loading">
    <h1>Loading...</h1>
  </div>
  <div id="corellium-error" style="display: none">
    <h1>Error</h1>
  </div>
</div>

4. Exchange your API token for a JWT

Your app code should create a request to obtain a JWT.

const projectId = '1234';                 // The ID of the project you want to use
const instanceId = '5678';                // The ID of the instance you want to use
const features = { connect: true };       // The features you want to enable

const res = await fetch('http://localhost:8000/api/auth', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    projectId,
    instanceId,
    features,
  }),
});

const { token, ...data } = await res.json();

For more information on the options you can pass to the API, see Configuring the Webplayer.

5. Instantiating the Webplayer

Once you have a JWT you can now instantiate the Webplayer. There are two primary methods of installation:

NPM Package

Install the Webplayer client from NPM:

npm install @corellium/corellium-webplayer

Then, in your app code, import the Webplayer client and instantiate it, by passing the JWT and the various options.

import CorelliumWebplayer from '@corellium/corellium-webplayer';

const webplayer = new CorelliumWebplayer({
  token,
  domain: corelliumDomain,
  instanceId,
  containerId: 'corellium-webplayer',
});

Script Tag

You can also include the Webplayer client as a script tag in your HTML using unpkg:

<script src="https://unpkg.com/@corellium/[email protected]/dist/index.global.js"></script>

<script>
  const webplayer = new CorelliumWebplayer.default({
    token,
    domain: corelliumDomain,
    instanceId,
    containerId: 'corellium-webplayer',
  });
</script>

---

For working examples in React and Next.js, check out our example projects.