LogoLogo
WebsiteBlogForumsSign up
  • Welcome
  • How Ready Player Me works
  • FAQ
  • 👩‍💻Integration Guides
    • Overview
    • Unity
      • Quickstart
      • Avatar Creator Integration
        • WebView Avatar Creator
          • Avatar Creator for Android & iOS
          • Avatar Creator for WebGL
        • Build your own Avatar Creator
          • Start with the sample
          • Elements
            • Asset Selection Element
            • Color Selection Element
            • Template Selection Element
            • Body Shapes Selection Element
            • Gender Selection Element
            • Avatar List Element
            • Photo Capture Element
            • Signup Element
            • Login Element
            • Logout Element
          • User Management
      • Load 2D Renders
      • Avatar Loader Window
      • Setup Multiplayer
      • Setup for XR (Beta)
        • Setup the Player Avatar
        • Setup Meta Movement SDK
        • Setup Final IK
        • Setup XR Hands
          • RpmHandDriver script
        • Facial Animations
        • VR Avatar Creator
      • Animations
        • Ready Player Me Animation Library
        • Mixamo Animations
      • Optimize
        • Avatar Configuration
        • Avatar Caching
        • Defer Agents
      • Code Samples
        • Loading 3D Avatars
        • Loading 2D Avatars
        • Avatar Creator (WebGL)
        • Avatar Creator (Desktop)
        • Avatar Creator (Mobile)
        • Distance-based LODs
      • Troubleshooting
        • Editor UI Window Issues
        • Avatar loading issues
        • iOS issues
        • WebGL issues
        • Firewall issues
        • Updating the SDK
          • Unity SDK 3.0.0 Migration guide
          • Unity SDK 4.0.0 Migration guide
          • Unity SDK 5.0.0
          • Unity SDK 7.0.0
          • WebView 2.0 Migration
        • Package installation issues
      • Help us improve the Unity SDK
      • FAQ for Unity
      • Early Access Features
    • Unreal Engine
      • Quickstart
        • Import SDK Manually
      • Avatar Creator Integration
        • Build your own Avatar Creator
          • Sample Structure
          • Customization Guide
        • WebView Avatar Creator
      • Load Avatars
      • Animations
        • Ready Player Me Animation Library
        • Loading Mixamo animations
        • Mannequin animation retargeting
        • Blender FBX export to UE
        • Oculus Lipsync integration
      • Optimize
        • Avatar configuration
        • Avatar caching
        • Avatar preloading
      • Code Samples
        • Unreal Engine 5 samples
        • Lyra project integration example
        • VR Avatars
        • Unreal Engine 4
      • Troubleshooting
        • Project compilation issues
        • Missing materials on built applications
        • Avatar loading issues
        • Animation issues
        • Unreal SDK breaking changes
        • Avatar lighting issues
        • Updating from earlier versions
          • Unreal SDK 3.0.0 Migration guide
        • Auto LOD issues
      • Help us improve the Unreal Engine SDK
      • FAQ for Unreal Engine
      • Early Access Features
    • React
      • Quickstart
    • React Native
    • iOS Native
    • Android Native
    • Web Integration
      • Quickstart
      • User Management
        • Guest Accounts
        • Account Linking
      • Avatar Creator integration
      • Optimize
    • API Integration
      • Quickstart
      • Custom Avatar Creator
      • User management
        • Ready Player Me Account
        • Anonymous Accounts
    • UX/UI Guidelines
      • Summary & quick tips
      • UX and UI guidelines and essentials
        • Foundation for good user experience
          • Layout
          • Colors
          • Typography
          • Icons
          • Dark mode and light mode
        • Mobile best practices
          • Layout
        • Making Ready Player Me feel native
          • Seamless Avatar Integration
          • Consistent Branding
          • Responsive Layout
          • Performance Optimization
        • Discoverability of the avatar editor
          • Onboarding tutorial
          • Clear navigation
          • Contextual Placement
  • 🖌️Customizing Guides
    • Studio (Developer Dashboard)
    • Avatar Creator Appearance
      • Avatar URLs
      • Avatar Shortcodes
    • Upload and Manage Custom Assets
      • Asset Manager in Studio
      • Configure in Studio
      • Manage custom assets using the API
      • Unlocking assets through API (Beta)
    • Create Custom Assets
      • Fullbody Outfits
        • Checking Skin Weights
      • Tops, Bottoms, Shoes
        • Editing templates
      • Hairstyle
      • Headwear
      • Facewear
      • Glasses
      • Hero Characters
      • Modeling Guidelines
  • 🔃API Reference
    • REST API
      • Authentication
      • Avatars
        • GET - 3D avatar
        • GET - 2D Render of an Avatar
        • GET - Metadata
        • PUT - Equip an asset
        • PUT - Unequip an asset
      • Assets
        • Asset Entity Properties
        • POST - Create Asset
        • GET - List Assets
        • PATCH - Update Asset
        • POST - Upload Asset Files
        • POST - Add Asset to Application
        • DELETE - Remove Asset from Application
        • PUT - Unlock asset for a user
        • PUT - Lock asset for a user
      • Users
        • POST - Create User
      • Auth
        • GET - Token
      • Changelog
    • Avatars
      • Full-body avatars
      • Full-body XR avatars
      • Half-body avatars
      • Morph targets
        • Apple ARKit
        • Oculus OVR LipSync
    • Avatar Creator
  • 🔉Support
    • Forums
    • Licensing & Privacy
Powered by GitBook
On this page
  • Subscribe to Events
  • Avatar Creator Configuration

Was this helpful?

  1. Integration Guides
  2. Web Integration

Avatar Creator integration

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

PreviousAccount LinkingNextOptimize

Last updated 10 months ago

Was this helpful?

If you followed the 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 API that can be used to subscribe to events and for triggering certain actions. The 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

v1.subscription.created

v1.subscription.deleted

v1.avatar.exported

v2.avatar.exported

v1.user.set

v1.user.updated

v1.user.logout

v1.user.authorized

Queries

Supported messages that can be posted to the iframe after the v1.frame.ready event has been emitted.

Effect
Message example

Logout user

Refresh unlocked assets

Avatar Creator Configuration

The available parameters, values, and their effects are described in the following table.

Parameter
Value
Effect

frameApi

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

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

Enables subscribing to postMessage events provided by the iframe. See more about below.

👩‍💻
{
  eventName: 'v1.frame.ready',
  source: 'readyplayerme'
}
{
  correlationId,
  data: { eventName },
  eventName: 'v1.subscription.created',
  source: 'readyplayerme',
  statusCode: 201
}
{
  correlationId,
  data: { eventName },
  eventName: 'v1.subscription.deleted',
  source: 'readyplayerme',  
  statusCode: 200
}
{
  data: {
    avatarId,
    url,
    userId,
  }, 
  eventName: 'v1.avatar.exported',
  source: 'readyplayerme', 
}
{
  data: {
    avatarId,
    url,
    userId,
    metadata: {
      gender,
      bodyType,
      ...
    }
  }, 
  eventName: 'v2.avatar.exported',
  source: 'readyplayerme', 
}
{
  data: { id },
  eventName: 'v1.user.set',
  source: 'readyplayerme',
}
{
  data: { id },
  eventName: 'v1.user.updated',
  source: 'readyplayerme',
}
{
  correlationId,
  eventName: 'v1.user.logout'
  source: 'readyplayerme'
  statusCode: 200
  type: 'queryResponse'
}
{
  data: { id },
  eventName: 'v1.user.authorized'
  source: 'readyplayerme'
  statusCode: 200
  type: 'queryResponse'
}
iframe.contentWindow.postMessage(
  JSON.stringify({
    target: 'readyplayerme',
    type: 'query',
    eventName: 'v1.user.logout'
  }),
  '*'
);
iframe.contentWindow.postMessage(
  JSON.stringify({
    target: 'readyplayerme',
    type: 'query',
    eventName: 'v1.asset.unlocked'
  }),
  '*'
);
Studio
messaging
Quickstart
post message
example code from the Quickstart