The Hyperbeam profile API allows you to persist session state including bookmarks, history,
passwords, and cookies which can be loaded into another session at a later time. This
allows you to resume sessions without requiring the user to open up web pages or
authenticate again.
Basic Usage
In order to save a session, the profile
parameter must be set to true
when
starting a Chromium session.
Saved sessions that have not been accessed for three months expire and are deleted automatically
Example Request
curl --request POST \
--url https://engine.hyperbeam.com/v0/vm \
--header 'Authorization: Bearer AUTH_VALUE' \
--header 'Content-Type: application/json' \
--data '{
"profile": true
}'
After the session is created, the response object will contain a session_id
property that you must save
in order to load the session state again afterwards.
Example Response
{
"session_id": "52f968cb-6739-4197-83d7-2305fe5d6f54",
"embed_url": "https://vwdrccwgpv181powg61ggyvy.hyperbeam.com/Uvloy2c5QZeD1yMF_l1vVA?token=c8iw3SmQglOU0ugfLr3dWY2LalSKI_WOGUldEt8knbw",
"admin_token": "51JOZEEcMp4trCwbpTS3jjQc0lSmeAZpPfxioDqe73U"
}
In order to load and update a previous session, the profile
parameter must be set to the session_id
you would like to resume
when starting a Chromium session.
curl --request POST \
--url https://engine.hyperbeam.com/v0/vm \
--header 'Authorization: Bearer AUTH_VALUE' \
--header 'Content-Type: application/json' \
--data '{
"profile": <session_id>
}'
This will load the profile associated with <session_id>
and update its contents when the new session is terminated. Below is a code snippet that showcases a simple profile integration:
app.get("/computer", async (req, res) => {
// Get the session ID from a query parameter
// In a real application you want to authenticate the user retrieve the session ID from your database
let { session_id } = req.query;
let profile = true; // profile = true will create a new profile
if (session_id) {
try {
await db.get(session_id);
profile = session_id; // if session_id is valid, load and update the profile tied to that id
} catch (e) {
res.status(400);
return;
}
}
const settings = {
profile,
timeout: {
offline: 10,
},
ublock: true,
};
const headers = {
Authorization: `Bearer ${process.env.HB_API_KEY}`,
};
let resp;
try {
resp = await axios.post("https://engine.hyperbeam.com/v0/vm", settings, {
headers,
});
} catch (e) {
console.error(e);
res.status(501);
res.send({ message: e.message });
return;
}
const computer = resp.data;
// if session_id was not defined, then a new profile was created and we want to store the session id tied to the new profile
// otherwise use the old session id
session_id = session_id || computer.session_id;
await db.put(session_id, {
session_id,
sites: [],
});
res.send(computer);
});
Advanced Usage
For more granular control, you can specify separate profiles to load and overwrite. This is useful if you wish to create a new profile from an existing profile, without altering the original.
curl --request POST \
--url https://engine.hyperbeam.com/v0/vm \
--header 'Authorization: Bearer AUTH_VALUE' \
--header 'Content-Type: application/json' \
--data '{
"profile": {
"save": <session_id_1>,
"load": <session_id_2>
}
}'
How Do We Persist Sessions?
When profile
is set to true
, we encrypt and store the Chrome profile of the session in Amazon S3.
This Chrome profile is associated with the session_id
that was returned to you on session creation.
When profile
is set to a session ID, we look for a stored Chrome profile that corresponds to that session_id
, and decrypt and
load the Chrome profile if there is a match.
This results in bookmarks, history, cookies, and passwords being persisted.