Getting Started

On this page you'll learn how to:

Embed an Avatar Creator iframe in a webpage.
Configure avatar optimization settings.
Configure your API Key.
Export an avatar from the Avatar Creator to MSquared.

There are two versions of this guide below. One that uses our template, and one that assumes you want to embed the Avatar Creator in your own website. If you get stuck on the latter, try checking the template code for some pointers.

Using our template?

Embed the Avatar Creator

On dash.msquared.io, go to Projects > [Your Project] > Avatar Creators and either create an Avatar Creator, or select an existing one that you want ot embed.
Copy the URL field.
Clone github.com/msquared-io/avatars-example-web-app
Create a .env file in the root of the repository and set the following variable: NEXT_PUBLIC_MSQUARED_AVATAR_CREATOR_URL = [the URL you copied in step 2]
Also set: MSQUARED_PROJECT_ID. You can find this on dash.msquared.io/projects.

Configure avatar optimization settings.

On dash.msquared.io, go to Projects > [Your Project] > Optimization Settings and either select Create Optimization Settings, or select an existing one.
Select an Optimization Preset. This determines the level of detail that created avatars will be stored at.
Copy the Optimization Settings ID field.
Add this to your .env file: MSQUARED_OPTIMIZATION_SETTINGS_ID = [your Optimization Settings ID]

Configure your API Key

On dash.msquared.io, go to Organizations > [Your Organization] > API Keys and select Create API Key.
Copy the API Key Token and store it in your .env file like so: MSQUARED_API_KEY = [Your API Key Token]
Select Create API Key Permission and input the following:
1. Project Id: [Your Project]
2. Resource: Avatars
3. Verb: Write
Select Create.

Export an avatar from the Avatar Creator to MSquared.

Save your .env file.
Run npm run dev from the repository root.
Visit http://localhost:3000
1. or the address shown in your console if port 3000 is not available.
Customize your avatar and when ready select Export.
This will upload and process your avatar. Once that's done, you'll see a Download button.

Using your own website?

Embedding the Avatar Creator

Go to Projects > [Your Project] > Avatar Creators and either create an Avatar Creator, or select and existing one that you want ot embed.
Copy the URL field.
Add the URL as an iframe on your website like so: <iframe src={MSQURED_AVATAR_CREATOR_URL}/>

A Window event listener should be setup, see the example below, to listen for when a user exports their completed avatar and then the avatarMml string should be sent to your backend for forwarding to MSquared APIs for processing.

Export events have the format:

data: {
  type: "MSQUARED_AVATAR_EXPORT"
  avatarMml: string
}

A window event listener can be configured to listen for these events:

const handleAvatarExport = async (event: {
        origin: string;
        data: {
            type: string;
            avatarMml: string;
        };
    }) => {
        // Vaidate the event.
        if (event.data.type !== "MSQUARED_AVATAR_EXPORT") {
            return;
        }
        const avatarMml = event.data.avatarMml;
        if (!avatarMml) {
           return;
        }
        // Send the avatarMml to be processed.     
        // ...
    };
window.addEventListener("message", handleAvatarExport);

The handler should send the avatarMml string to your backend which may then call the MSquared avatar processing API with the MSquared API key. It is not recommended to do this directly from the web app as this would expose the API key and you could be at risk of users using the key for themselves.

Client side setup using react:

import { useConfig } from '@/utils/theme';
import { useEffect, useState, useCallback } from 'react';

const MSQURED_AVATAR_CREATOR_URL = process.env.MSQURED_AVATAR_CREATOR_URL;
const YOUR_BACKEND_PROCESSING_ENDPOINT = "";

export function Creator() {
    const [isLoading, setIsLoading] = useState(false);
    
    const handleAvatarExport = useCallback(async (event: {
        origin: string;
        data: {
            type: string;
            avatarMml: string;
        };
    }) => {
        // Validate the event.
        if (event.data.type !== "MSQUARED_AVATAR_EXPORT") {
            return;
        }
        const avatarMml = event.data.avatarMml;
        if (!avatarMml) {
           return;
        }
        
        // Set loading state and send the avatarMml to be processed.
        try {
            const response = await fetch(YOUR_BACKEND_PROCESSING_ENDPOINT, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({ avatarMml }),
            });
            
            if (!response.ok) {
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            
            const result = await response.json();
            if (result.mmlUrl) {
                console.log(result.mmlUr);
            }
        } catch (error) {
            console.error(error);
        }
    }, []);

    useEffect(() => {
        window.addEventListener("message", handleAvatarExport);
        
        return () => {
            window.removeEventListener("message", handleAvatarExport);
        };
    }, [handleAvatarExport]);

    return (
        <div>
            <iframe src={MSQURED_AVATAR_CREATOR_URL} />
        </div>
    )
}

Configuring your backend

Your backend must provide a processing endpoint it can send avatarMml string to to be processed. This endpoint must call the MSquared Avatars processing endpoint with the avatarMml, optimizationSettingsId and a valid apiKey as the bearer token. The apiKey must be configured through the MSquared Dashboard with write permission on the avatars resource.

The optimizationSettingsId is available from the MSquared dashboard - go to Optimization Settings under the Avatars section; create a new one and use the ID. Inside the Optimization Settings you can configure the quality of the processed avatar.

For more information see the Optimization Settings page.

Example Processing Request

Where variables:

PROJECT_ID - MSquared Project ID from the MSquared Dashboard
OPTIMIZATION_SETTINGS_ID - Optimization Settings ID from the MSquared Dashboard
API_KEY - MSquared API key with write permission on avatars
AVATAR_MML - The string output from the Avatar Creator and sent to your backend

curl -X PUT "https://api.msquared.io/v1/avatars/${PROJECT_ID}/optimization-settings/${OPTIMIZATION_SETTINGS_ID}/process" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"avatarMml": "AVATAR_MML"}'

Checkout the API spec here.

Expected Response

{
    mmlUrl: string
    glbUrl: string
}

Interested in integrating Avatars with your Web World? Checkout the Web Worlds auth webhooks guide to see how to easily link these two system together!

PreviousOptimization Settings NextBuilding your catalog

Last updated 2 months ago

Was this helpful?