Avatar Creator integration

Integrate the Avatar Creator in your game or app as an iframe or WebView.

If you followed the Quickstart you already integrated the Avatar Creator into a website using an iframe. This guide details the integration and customization options of this Avatar Creator.

Subscribe to Events

The iframe exposes a post message API that can be used to subscribe to events and for triggering certain actions. The example code from the Quickstart shows how to set up the subscription handler and how to trigger custom code on different events.

To enable the events you need to append the parameter ?frameApi to the avatar-creator URL.

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

Emitted Events

All messages that the iframe emits will always contain a eventName and source and can be used for filtering the output that is emitted. See the table below for all the 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', }
v2.avatar.exported	{ data: { avatarId, url, userId, metadata: { gender, bodyType, ... } }, eventName: 'v2.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 user	iframe.contentWindow.postMessage( JSON.stringify({ target: 'readyplayerme', type: 'query', eventName: 'v1.user.logout' }), '*' );
Refresh unlocked assets	iframe.contentWindow.postMessage( JSON.stringify({ target: 'readyplayerme', type: 'query', eventName: 'v1.asset.unlocked' }), '*' );

Avatar Creator Configuration

While you can configure most of the Avatar Creator features from Studio, for some use cases it might be helpful to do it by providing a query string to the URL.

The available parameters, values, 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.
selectBodyType		Enables selecting between halfbody and fullbody avatars.
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

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