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: {
    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 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

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: { 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' }

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' }), '*' );

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

Quickstart

Optimize

Last modified 2mo ago