Avatar Creator

Integrate the Avatar Creator via iframe or WebView.

The Avatar Creator can be integrated into your app via iframe or WebView. The communication between your app or game and the Avatar Creator is by postMessage.

Emitted Events

All messages emitted by the iframe contain an eventName and source which can be used for filtering the emitted output. See the table below for all currently supported events and their sample outputs.

EventPayload example

v1.frame.ready

{
  eventName: 'v1.frame.ready',
  source: 'readyplayerme'
}

v1.subscription.created

{
  correlationId,
  data: { eventName },
  eventName: 'v1.subscription.created',
  source: 'readyplayerme',
  statusCode: 201
}

v1.subscription.deleted

{
  correlationId,
  data: { eventName },
  eventName: 'v1.subscription.deleted',
  source: 'readyplayerme',  
  statusCode: 200
}

v1.avatar.exported

{
  data: {
    avatarId,
    url,
    userId
  }, 
  eventName: 'v1.avatar.exported',
  source: 'readyplayerme', 
}

v1.user.set

{
  data: { id },
  eventName: 'v1.user.set',
  source: 'readyplayerme',
}

v1.user.updated

{
  data: { id },
  eventName: 'v1.user.updated',
  source: 'readyplayerme',
}

v1.user.logout

{
  correlationId,
  eventName: 'v1.user.logout'
  source: 'readyplayerme'
  statusCode: 200
  type: 'queryResponse'
}

v1.user.authorized

{
  data: { id },
  eventName: 'v1.user.authorized'
  source: 'readyplayerme'
  statusCode: 200
  type: 'queryResponse'
}

Queries

Supported messages that can be posted to the iframe after the v1.frame.ready event has been emitted.

EffectMessage example

Logout the user

iframe.contentWindow.postMessage(
  JSON.stringify({
    target: 'readyplayerme',
    type: 'query',
    eventName: 'v1.user.logout'
  }),
  '*'
);

Avatar Creator configuration

You can configure the features of the Avatar Creator by providing a query string to the URL.

See all avatar creator options ->

The available parameters, their values if necessary, and their effects are described in the following table.

ParameterValueEffect

frameApi

Enables subscribing to postMessage events provided by the iframe. See more about messaging below.

clearCache

Disables caching avatar customization and restarts the app upon refreshing the iframe or when creating a new instance.

bodyType

'halfbody' | 'fullbody'

Selects a body type for the avatar in the editor or allows the user to choose from both. Please note, that this only influences the behavior of the avatar-creator, but not the avatar-type you get on requesting an avatar. If you want to change that too, please contact

id

If an "id" query parameter is specified, Avatar Creator loads the corresponding avatar. For registered and guest users, not providing an "id" parameter will redirect them to the "Choose avatar" page. Anonymous users will have the last used avatar loaded in the editor automatically if they don't specify an "id" parameter.

Examples

https://yourappname.readyplayer.me/avatar?frameApi

https://yourappname.readyplayer.me/avatar?clearCache&bodyType=halfbody

Default Language

The Avatar Creator automatically picks the system/browser language of the user's device. To set a different default language, do one of the following.

This is not available from Studio. You need to modify the URL of the Avatar Creator.

To change the language, include the language code in the URL path.

Example URL for setting German as the default language.

https://yoursubdomain.readyplayer.me//avatar

Supported languages and their language codes

LanguageCode

English

en

English (Ireland)

en-IE

German

de

French

fr

Spanish

es

Spanish (Mexican)

es-MX

Portuguese

pt

Portuguese (Brazil)

pt-BR

Italian

it

Turkish

tr

Japanese

jp

Korean

kr

Chinese

ch

Clear Cache

By default, the Avatar Creator uses local browser storage to store and restore a user's session, such as their login state and current avatar creation step.

If you want to disable this behavior, for example, if multiple users are using the same device, use the ClearCache parameter.

Open the Avatar Creator with the query string ?clearCache

https://demo.readyplayer.me/de/avatar?clearCache

User Session restoration, account linking, and Token Parameter

To restore user sessions, you can still utilize the "token" parameter. For detailed information on how to use this parameter, please refer to our documentation at Login on Behalf of a User and Request a Token. Post Message API and Event Consistency Avatar Creator maintains consistency with the previous version regarding emitted events, as outlined in our public documentation. The Post Message API, used for communication and interaction with the editor, continues to function seamlessly, ensuring that existing integrations and workflows remain unchanged. This means that the events you've come to rely on for real-time updates and interactions with the editor will still be available, allowing for a smoother transition to Avatar Creator. We encourage you to refer to our documentation for detailed information on utilizing the Post Message API to enhance your integration with the editor.

Last updated