---
title: "Using the Lab Client API to Customize Labs"
slug: "lab-client-api-for-lab-delivery-customization"
updated: 2025-08-28T19:04:16Z
published: 2025-08-28T19:04:16Z
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skillable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the Lab Client API to Customize Labs

## Overview

The Lab Client API is a public, managed client-side API that allows you to customize and integrate labs into your own applications or portals. It provides two ways to interact with the lab client:

- **Direct JavaScript access**: Call methods directly from theme scripts using the global `window.api` object.
- `postMessage`**integration**: Send and receive messages between the lab client (when embedded in an Iframe) and your parent application.

Lab developers have historically customized the lab client using internal or private JavaScript APIs. The risk with this method is that changes to internal APIs can cause labs to break, leading to support issues and deployment risks.

To address this, we developed the Lab Client API. This API provides a stable, supported interface for customization, allowing customers to safely integrate with the lab client while giving our internal teams the flexibility to evolve the platform without impacting existing integrations.

### Benefits

- Eliminates breakage caused by internal API changes
- Enables safe, supported customization for customers and internal teams
- Supports robust automated testing of public APIs
- Accelerates onboarding and ensures safer deployments
- Unlocks new capabilities for integrators and power users

### Intended Audience

This API is designed for users who need to customize or extend the lab client through stable, supported integrations. It primarily supports these groups:

- Lab developers and admins integrating with external systems
- Customers requiring custom workflows

Typical roles include:

- Lab Developer
- Admin
- Integration Engineer
- Power User

## Key Features

The Lab Client API is designed to give you flexibility whether you're working inside the lab client or embedding it into your own site.

### Global API Object ( `window.api` )

The global API object is available on all top-level lab client pages, including `LabClient`, `VirtualizationClient`, and `Instructions`. It provides a stable, documented, and versioned interface with uniform method signatures and responses (regardless of the page context).

Each lab client page exposes a global `window.api` object in the JavaScript namespace.

### JavaScript Access

Use a set of JavaScript methods and events inside theme scripts. Calling API methods directly through `window.api` lets you integrate custom logic and behaviors right inside your lab Themes for a simple, fast, flexible solution.

### postMessage Interface

All API methods are available via standard browser `postMessage` calls. Parent applications embedding the lab client in an iframe can:

- Send commands (e.g., "go to instruction page 7")
- Receive notifications on events like VM state changes, instruction page changes, and activity completion

Communication is secure, asynchronous, and based on standard browser messaging.

#### How it Works

If you're embedding the lab client in an iframe (for example, inside your portal or LMS), you can use the `postMessage` API to send commands to the lab and listen for events, following this workflow:

1. Your parent application sends a message, with the method name and any required parameters, to the lab client.
2. The lab client executes the method and sends a response back when needed.
3. The lab client also broadcasts important events automatically to the parent.

#### Benefits

- Seamless integration with portals, LMS platforms, or other external applications.
- Asynchronous, decoupled communication between the host and the lab client that doesn't block or slow down your application.
- Flexible workflows that support both direct commands and even-driven integrations.

### Backward Compatibility and Safety

To support our efforts in providing a secure, stable public API, we plan to deprecate older internal and private APIs. The Lab Client API is the supported path going forward, with ongoing versioning, testing, and documentation to ensure long-term stability.

## Lab Client API Methods by Category

| Category | Method/Event | Description | Available via JavaScript | Available via postMessage |
| --- | --- | --- | --- | --- |
| **Environment Monitoring** | `getEnvironmentConnectionStatus()` | Returns current VM connection status | ✅ | ✅ |
| `getEnvironmentLatency()` | Returns current latency metrics | ✅ | ✅ |
| `onEnvironmentConnectionStatusChange` | Fires an event when the VM connects/disconnects | ✅ | ✅ |
| **Lab Interaction** | `sendTextToEnvironment(text)` | Sends (pastes) text into the active VM | ✅ | ✅ |
| `sendLabNotification(notification)` | Sends a notification within the lab client | ✅ | ✅ |
| **Lab Variables and Tokens** | `getLabVariable(name)` | Gets the value of a named lab variable | ✅ | ✅ |
| `setLabVariable(name, value)` | Sets the value of a named lab variable | ✅ | ✅ |
| `getLabToken(name)` | Retrieves a named lab token | ✅ | ✅ |
| `onLabVariableChanged` | Fires an event when a lab variable changes | ✅ | ✅ |
| **Instructions Navigation** | `getInstructionsPageIndex()` | Returns the current instructions page index | ✅ | ✅ |
| `gotoInstructionsPage(index)` | Navigates to a specific instructions page | ✅ | ✅ |
| `onInstructionsPageChanged` | Fires an event when the instructions page changes | ✅ | ✅ |
| **Activity Tracking** | `evaluateActivity(alias)` | Triggers evaluation of a specific activity | ✅ | ✅ |
| `onActivityCompleted` | Fires an event when a lab activity is completed | ✅ | ✅ |
| **Session Timing** | `getMinutesRemaining()` | Returns the number of minutes left in the lab session | ✅ | ✅ |

## Common Use Cases

Use the Lab Client API to extend and customize lab experiences in various ways. Here are some common scenarios and the methods they use:

### 1. Manage lab variables programmatically

Create, update, and retrieve lab variables, as well as obtain lab tokens, without using the UI.

**Example scenarios:**

- Automate lab setup for new courses
- Bulk update lab variables for a training event

**API methods/events used**: `getLabVariable`, `setLabVariable`, `getLabToken`

### 2. Integrate labs in a parent application (via `postMessage`)

Embed the lab client in an iframe and control it directly from your application or portal using the `postMessage` interface.

**Example scenarios:**

- A customer portal embeds the lab client and tracks learner progress
- A parent app customizes instruction navigation

**API methods used**: All API methods and events are accessible via `postMessage`.

### 3. Monitor and react to environment connection status

Detect when a VM connects or disconnects, and update the user experience accordingly.

**Example scenarios:**

- Show a warning if a VM disconnects
- Log connection drops for analytics

**API methods used**: `getEnvironmentConnectionStatus`, `onEnvironmentConnectionStatusChange`

### 4. Automate text input in lab environments

Send commands, credentials, or code snippets directly into a VM for demos, testing, or guided labs.

**Example scenarios:**

- Auto-fill credentials
- Paste code samples for users

**API methods used**: `sendTextToEnvironment`

### 5. Track and control instructions navigation

Monitor and control the flow of lab instructions, making it easy to align with custom learning paths or LMS integrations.

**Example scenarios:**

- Advance instructions based on external triggers in a parent app
- Track which instruction page a user is currently on

**API methods used**: `getInstructionsPageIndex`, `gotoInstructionsPage`, `onInstructionsPageChanged`

### 6. Monitor and respond to activity completion

Detect when users complete lab activities and trigger external workflows, progress tracking, or gamification.

**Example scenarios:**

- Award badges when an activity is complete
- Sync user progress with an external LMS

**API methods used**: `evaluateActivity`, `onActivityCompleted`

### 7. Manage lab session timing

Monitor session time remaining and take action before a lab expires.

**Example scenarios:**

- Show a countdown timer to the learner
- Auto-save user work before time runs out

**API methods used**: `getMinutesRemaining`

### 8. Manage lab variables dynamically

Update and monitor lab variables in real time on adaptive labs or integrations.

**Example scenarios:**

- Update environment settings on the fly
- Sync lab variables with external systems

**API methods used**: `getLabVariable`, `setLabVariable`, `onLabVariableChanged`

## Example Workflows

These examples show how you can combine multiple API methods to build common integrations. Each workflow includes the goal, flow, and a sequence diagram to illustrate the interaction between the parent application and the lab client.

### 1. Auto-fill credentials on VM connection

Automatically send login credentials to the VM when it connects.

**Workflow:**

1. The parent app listens for `onEnvironmentConnectionStatusChange` .
2. When the status is **Connected**, the parent app calls `sendTextToEnvironment` with credentials.

**API methods used:**`onEnvironmentConnectionStatusChange` , `sendTextToEnvironment(text)`

| Sequence Diagram | Sample Code |
| --- | --- |
| ![](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/image(693).png) | ```plaintext sequenceDiagram participant ParentApp participant LabClient LabClient->>ParentApp: postMessage (onEnvironmentConnectionStatusChange: "connected") ParentApp->>LabClient: postMessage (event_id: "sendTextToEnvironment", text: "username/password") LabClient-->>LabClient: Executes sendTextToEnvironment(text) ``` |

### 2. LMS-driven instructions navigation

Let an LMS system control which instruction page learners see.

**Workflow:**

1. The LMS sends `gotoInstructionsPage(index)` via `postMessage`.
2. The lab client navigates to the page.
3. The lab client broadcasts `onInstructionsPageChanged` .

**API methods used:**`gotoInstructionsPage(index)` , `onInstructionsPageChanged`

| Sequence Diagram | Sample Code |
| --- | --- |
| ![](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/image(694).png) | ```plaintext sequenceDiagram participant LMS participant LabClient LMS->>LabClient: postMessage (event_id: "gotoInstructionsPage", index: 3) LabClient-->>LabClient: Executes gotoInstructionsPage(index) LabClient->>LMS: postMessage (event_id: "onInstructionsPageChanged", index: 3) ``` |

### 3. Award badge on activity completion

Gamify the lab experience by awarding badges when activities are completed.

**Workflow:**

1. The lab client sends `onActivityCompleted` via `postMessage`.
2. The parent app receives it and triggers badge-awarding logic.

**API methods used:**`evaluateActivity(alias)` , `onActivityCompleted`

| Sequence Diagram | Sample Code |
| --- | --- |
| ![](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/image(695).png) | ```plaintext sequenceDiagram participant LabClient participant ParentApp LabClient->>ParentApp: postMessage (event_id: "onActivityCompleted", activity: "quiz1") ParentApp-->>ParentApp: Triggers badge award logic ``` |

### 4. Show countdown timer in parent app

Show the remaining lab time directly in the parent app UI.

**Workflow:**

1. The parent app sends `getMinutesRemaining` via `postMessage`.
2. The lab client responds with the remaining time.
3. The parent app updates the timer display.

**API methods used:**`getMinutesRemaining`

| Sequence Diagram | Sample Code |
| --- | --- |
| ![](https://cdn.document360.io/a298db04-a0fe-47e0-bfe3-c52d6f9d7c8c/Images/Documentation/image(696).png) | ```plaintext sequenceDiagram participant ParentApp participant LabClient ParentApp->>LabClient: postMessage (event_id: "getMinutesRemaining") LabClient-->>ParentApp: postMessage (event_id: "getMinutesRemaining", value: 12) ParentApp-->>ParentApp: Updates countdown timer ``` |

The interface that the user sees as they work in a lab. The interface is presented in a HTML5 compatible browser and normally contains two major components. One component presents the service the Learner will interact with, and the second component contains instructions and other resources to guide the Learner.

An API, also known as an Application Programming interface, consists of a defined set of rules and protocols that enable seamless communication between different software applications. A common language for software systems to collaborate effectively.

Iframes allow web pages to be embedded within other pages. While they enhance user experience during lab launches, it's crucial to note that iframes can sometimes introduce hidden issues compared to launching the lab directly in Skillable Studio.

Themes allow styling to be configured for a lab profile, to provide a custom look and feel.

A Learning Management System (LMS) is a software application that manages learning processes. It handles administrative tasks, class and course management, tracks learner progress, delivers educational content, and automates processes like enrollment and reporting and more.