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

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' }`

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

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

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

Parameter	Value	Effect
`frameApi`		Enables subscribing to `postMessage` events provided by the iframe. See more about 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

frameApi

Enables subscribing to postMessage events provided by the iframe. See more about 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

Examples

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

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

PreviousAccount Linking NextOptimize

Last updated 3 months ago