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.

Event	Payload 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.

Effect	Message 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.

Parameter	Value	Effect
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.
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

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

Language	Code
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.