Web - Ready Player Me – Developer Documentation

If your application lives on the web or has a user-facing web portal, you can integrate the Ready Player Me Avatar Creator via an <iframe>. 
Once a user creates an avatar, you can use its unique URL to import it into your web app or store it, for example, in a user profile. 
This also works for VR and other apps with a user-facing web-based administrative dashboard. 
Start with the Try Me! example or customize the GitHub example linked below. Both examples include code to create an iframe for the Avatar Creator on a webpage, and a script to retrieve the avatar URL once the user has finished creating it.
Sample code
​https://github.com/readyplayerme/Example-iframe​
Take a quick look
1.Go to https://github.com/readyplayerme/Example-iframe.
2.Save src/iframe.html.
3.Open the file in your browser. 
See also Firewalls.
Example
1.Go to https://github.com/readyplayerme/Example-iframe.
2.Dowlnload the HTML code in the src folder:  src/iframe.html.
3.Open the file in an editor. 
4.Find const subdomain and replace 'demo' with the yourappname portion your subdomain (https://yourappname.readyplayer.me).
5.Embed the iframe into your existing web frontend. 
6.The information in the <head> defines frame properties.
If you are not displaying full screen, set the width and height to 1280 x 800px for desktop and 720 x 1080px for mobile. 
7.The <script> sends a request to the readyplayer.me page. 
When the user has clicked the final Next button, a URL to the avatar asset is created and made available to the parent of the iframe. This script sets up an eventListener that catches and displays the avatar URL.
When a user customizes and re-exports their avatar, the updated avatar is made available through the same URL.
Configuration
Features that are accessible from the integration can be enabled by providing a query string to the URL. 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.
gender
'male' | 'female'
Selects a gender from the allowed values list. Also skips gender-selection step.
selectBodyType
​
Enables selecting between halfbody and fullbody avatars.
bodyType
'halfbody' | 'fullbody'
Selects a body type for the avatar. Also skips body type selection step when enabled.
Usage
https://yourappname.readyplayer.me/avatar?frameApi
https://yourappname.readyplayer.me/avatar?clearCache&gender=female&selectBodyType
Messaging
The iframe exposes a post message API that can be used to subscribe to events and for triggering certain actions. The example code shows how to set up the subscription handler and how to trigger custom code on different events.
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.eported',
  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'
}
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'
  }),
  '*'
);
Avatar API
Please check out the Avatar API to make more specific requests.
​Go to Avatar API Documentation​

SDKs & Integrations - Previous

React Native

Next - Other

Changelog

Last modified 2d ago

Copy link

On this page

Sample code

Take a quick look

Example

Configuration

Messaging

Avatar API