Register Face

Overview

Although templates are immutable once published (meaning they cannot be changed), faces for a given template can be added, modified, or removed even after the template is published.

This API will register a new face for a template. After a face is successfully registered, it can be used by front-end code to display a vAtom created from the specified template.

There are two types of faces on the BLOCKv platform:

1. Native faces to display the vAtom (for example as an icon in an inventory).
2. Faces that reference external "face code" written as HTML web apps (with optional additional features provided by the BLOCKv Face SDK), which can use multiple resources and more complex logic to display a vAtom.

Register Face Request

Content-Type: application/json
App-Id: {app_id}

Payload Details

Supported display URLs

Native display URLs (i.e. matching the pattern 'native://*') are used by the viewer to uniquely identify the Native Face View used to visually render the vAtom. Remote display URLs (i.e. matching the pattern 'https://*') all identify the Web Face View as the renderer. It is up to each viewer to decide which Face Views to include.

BLOCKv supports the face views detailed in the table below. For more information on configuring faces, see configuring faces.

Constraints object

Supported view modes

A view mode defines a visual context within a Viewer where a face is able to be displayed. Generally speaking, the view mode relates to the size of the frame in which face should be displayed – but may also include other attributes such as view hierarchy etc.

icon

The icon view_mode displays an image, video or 3D object that represents the vAtom in the user's inventory, among other places.

engaged

The engaged view_mode displays an enlarged version of the vAtom – typically shown after the user interacts with a vAtom in the icon view mode, e.g. such as tapping the vAtom. Adding a face that supports the engaged view mode is optional, and falling back on the icon view mode is a recommended viewer pattern.

card

The card view_mode is typically used to display the vAtom as an interactive card. The aspect ratio of the card should be 10:16 (if possible).

fullscreen

The fullscreen view_mode is typically used to display the vAtom over the entire screen.

Supported platforms

• generic
• ios
• android
• web

As a starting point, always set platform as generic, this will allow the face to be displayed by all viewer apps (independent of their platform). If you need to specialize the face per platform then consider using the platform specific constraints of ios, android, or web.

Supported qualities

Can be used by apps, for example to avoid loading high quality faces on a slow connection.

• low
• medium
• high

{
  "template": "publisher_fqdn::Template_Name::v1",
  "display_url": "native://video",
  "package_url": "native://video",
  "constraints": {
    "bluetooth_le": false,
    "contact_list": false,
    "gps": false,
    "three_d": false,
    "view_mode": "icon",
    "platform": "generic",
    "quality": "high"
  },
  "resources": [
    "ActivatedImage",
    "Video"
  ]
}

{
  "template": "publisher_fqdn::Template_Name::v1",
  "display_url": "native://progress-image-overlay",
  "package_url": "native://progress-image-overlay",
  "constraints": {
    "bluetooth_le": false,
    "contact_list": false,
    "gps": false,
    "three_d": false,
    "view_mode": "icon",
    "platform": "generic",
    "quality": "high"
  },
  "resources": [
    "ActivatedImage",
    "StartImage"
  ]
}

Register Face Response

Return & Error Codes

{
    "payload": {
        "success_message": "Registered face for template=publisher_fqdn::Template_Name, id=4c873f84-6fa5-4dc5-8367-8285f843b9b4"
    }
}