Skip to main content

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 projectId = 'my_project_id';
const apiToken = 'my_api_token';
const endpoint = 'my_endpoint.enterprise.corellium.com';
const snapshot = 'my_snapshot_id';

const corellium = new Corellium({
endpoint,
apiToken
});

const project = await corellium.createProject("Webplayer Project");
const instance = await project.createInstance({
name: 'Webplayer Device',
flavor,
os,
bootOptions: {
snapshot,
},
});

const projectId = project.id;
const instanceId = instance.id;

For each instance of a webplayer you should have one project containing one device.

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 projectId = '1234'; // The ID of the project you want to use
const instanceId = '5678'; // The ID of the instance you want to use
const expiresIn = 18000; // Token expiration, in milliseconds
const features = { connect: true; }; // The features you want to enable

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();

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

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 res = await fetch('http://localhost:8000/api/auth', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
token: apiToken,
projectId,
instanceId,
features,
}),
});

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

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,
deviceId,
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,
deviceId,
containerId: 'corellium-webplayer',
});
</script>