User Guide

Deprecated

This documentation covers Bodygram Estimation API which is now deprecated. Please refer to the Bodygram Platform for the latest documentation on Bodygram's most complete scanning solution.

This section presents a step-by-step integration guide to get you ready to use the body scanner widget in your web application.

Prerequisites

You need a client ID provided by Bodygram to start using the body scanner widget. The client ID is a static token that uniquely identifies your app when making requests to the body scanner API.

IMPORTANT: Do not publicly expose your client ID as it would allow others to interact with body scanner API on your behalf. If you have lost, forgotten, or exposed your client ID, please contact Bodygram's support to get a new one.

Before loading the body scanner widget, you need to request a new Scanning Session ID (SSID) using your client ID. In this guide, we assume that environment variable CLIENT_ID contains your client ID.

To request a new SSID, send a request such as the following from the backend of your application:

curl --location --request POST 'https://api.bodyscanner.bodygram.com/scanning/v0/create-session' \
--data-raw '{
    "clientId": "$CLIENT_ID"
}'

You should receive a successful response that is similar to the following:

{
    "scanningSession": {
        "scanningSessionId": "SSID_ABC123",
        "expireAtTimestamp": "2022-04-01T07:44:07.746059293Z"
    }
}

By default, the client ID is the only mandatory parameter to create a new SSID. However, it is possible to associate each new scanning session with a custom ID that you own (e.g. a user ID). To do this, set the clientScanningID parameter to the ID you want to associate with the session:

curl --location --request POST 'https://api.bodyscanner.bodygram.com/scanning/v0/create-session' \
--data-raw '{
    "clientId": "$CLIENT_ID",
    "clientScanningId": "MY_CUSTOM_ID_FOR_THIS_SESSION"
}'

Expected response:

{
    "scanningSession": {
        "scanningSessionId": "SSID_ABC123",
        "clientScanningId": "MY_CUSTOM_ID_FOR_THIS_SESSION",
        "expireAtTimestamp": "2022-04-01T07:44:07.746059293Z"
    }
}

The scanning session can be further configured by defining a ScanningConfig object in your request. For more information about the available options (and also potential errors), please refer to the API specification.

Once you have obtained an SSID, you can easily embed the body scanner widget in your web page as described in this step-by-step guide.

Step 2.a: Create a HTML Page

This guide is based on the following basic HTML page.

<!DOCTYPE html>
<html>
  <head>
    <title>Add Scan</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <link rel="stylesheet" href="https://widget.bodyscanner.bodygram.com/v0/widget.css" />
    <script src="./index.js"></script>
  </head>
  <body>
    <h3>Scan Demo</h3>
    <!--The div element for the Scan widget -->
    <div id="scan"></div>

    <script src="https://widget.bodyscanner.bodygram.com/v0/widget.js"></script>
  </body>
</html>

Step 2.b: Add scan to site with the Session ID

This section shows you how to load the body scanner widget to your web page, and how to write your own JavaScript to use the body scanner API.

const widget = new BodygramScanningWidget('scan', {
    ssid: 'my_SSID',
    systemOfMeasurement: 'metric', // imperial or metric. Default: metric
    os: 'ios',                     // Optional parameter, by default we will infer from the useragent. Example, 'ios' or 'android'
    version: '13.0.1',             // Optional parameter, by default we will infer from the useragent. Example, '1' or '1.0' or '1.2.3'
    onError: error => {},          // do something with the error object
    onResult: result => {},        // do something with the result object
    onLoad: () => {},              // do something after the iframe is loaded
})

widget.insert() // insert the widget
widget.toggle() // toggle the widget
widget.remove() // remove the widget from DOM

Understanding the code:

<script src="https://widget.bodyscanner.bodygram.com/v0/widget.js"></script>

In the snippet above, the script loads the BodygramScanningWidget API from the given URL. You can verify that it is properly loaded by checking if it exists in the window object. For example,

if (window.BodygramScanningWidget) {}

The BodygramScanningWidget is a class that accepts 2 parameters:

The ID of an HTML element (e.g. a div) that is meant to contain the body scanner widget;
A list of options.

const widget = new BodygramScanningWidget('scan', {
    ssid: 'my_SSID',
    systemOfMeasurement: 'metric', // imperial or metric. Default: metric
    userStats: {...userStats},     // optional parameter to pre-fill the form
    onError: error => {},          // do something with the error object
    onResult: result => {},        // do something with the result object
    onLoad: () => {},              // do something after the iframe is loaded
})

In the above example, new BodygramScanningWidget() creates a new body scanner widget that is then added in the HTML element with ID scan. In the second parameter, the ssid property tells the API which Session ID to use. Property systemOfMeasurement indicates what measurement system should be used between imperial or metric. If systemOfMeasurement is not set, metric is used by default.

In the third parameter, the userStats represents the user's height, weight, age and gender. If provided, the form will be pre-filled and validated as the user opens the widget. Depending on the systemOfMeasurement, userStats should be provided differently.

For example, when the systemOfMeasurement is metric, the userStats object should have the following properties:

const userStats = {
  heightCm: 180,
  weightKg: 80.5,
  age: 80,
  gender: 'male', // male or female
}

On the other hand, when the systemOfMeasurement is imperial, the userStats object should have the following properties:

const userStats = {
  heightFt: 6,
  heightIn: 0,
  weightLbs: 150.5,
  age: 80,
  gender: 'female', // male or female
}

The following properties define different call back functions:

onError: callback function called when an error has occured in the widget.
onResult: callback function called when a result has returned from the widget.
onLoad: callback function called when the widget is successfully loaded on to the web page.

After creating a new widget object, we will insert the widget to your web page using the insert() method.

widget.insert()

Once the widget is loaded, we can show/hide the widget using the toggle() method.

widget.toggle()

Once scanning is over, we can remove the widget using the remove() method.

widget.remove()

User Guide

Prerequisites

Step 1. Obtain a Session ID for embedding the widget

Step 2. Embed the Body Scanner widget in your page

Step 2.a: Create a HTML Page

Step 2.b: Add scan to site with the Session ID

Understanding the code: