Web Face

Overview

Displays a remote resource typically a web page.

The Web Face offers the greatest flexibility in terms of content and behavior of all the embedded faces. Developing a Web Face is similar to developing a responsive Web app and has all the same benefits. There are a few characteristics which make the Web face a good candidate:

• Custom content:

  • Web apps allow you to display content with custom layout and behavior. This is helpful if your use case does not fit one of the native embedded faces, e.g. Image Layered.

• Dynamically updatable:

  • Web Faces allow easier interaction with external services to drive content is fairly straightforward.

• Platform independent:

  • By design, Web Faces can be displayed in any viewer which support the native bridge.

Note: An alternative to creating a Web Face is to develop a custom Native Face. Native faces use native platform code and must therefore be written for each platform you intend to support.

Registering the Face

The example below shows how to register a Web face against your vAtom's template. Registering a Web face is as simple as specifying an https:// display URL instead of a native:// url. Once registered, viewers will show the web app at the target URL.

POST /v1/publisher/face

{
  "template": "MyTemplateName",
  "display_url": "https://demo.server.io/example-face",
  "package_url": ".",
  "constraints": {
    "bluetooth_le": false,
    "contact_list": false,
    "gps": false,
    "three_d": true,
    "view_mode": "card",
    "platform": "generic",
    "quality": "high"
  }
}

View Mode

Web apps typically provide a better user experience when in a larger visual context. For this reason, we recommend using the card or engaged view modes when registering your Web face.

Security: Only https display URLs are supported.

Building a Web Face

To build a Web Face we recommend using the BLOCKv Web Face SDK. Building your Web Face to leverage the BLOCKv Web Face SDK allows you to communicate with the underlying viewer. To get started install the Web Face SDK.

Installing the Web Face SDK

The Web Face SDK is hosted on npm and may be installed using:

- $ npm install @blockv/web-face-sdk

The Web Face SDK is dependent on the viewer implementing a "native bridge". The BLOCKv vAtoms app and those viewers built using the BLOCKv SDKs support Core functionality automatically.

Interacting with the BLOCKv platform (Core)

The Web Face SDK exposes a set of functions which allow your Web face to query for platform information, for example: vAtoms or user details. This essentially gives the Web face the ability to communicate with the BLOCKv platform without requiring the user to log in.

The following core functions are available:

Interacting with the Viewer

The Web Face SDK also allows for messages to be sent to the viewer. For example, your web app may want the viewer to show a particular vAtom or open the map interface.

Custom messages may be sent using:

Send custom viewer message

Blockv.sendMessage(name, data)

Face Message Support

It is up to each viewer to decide which, if any, custom face messages to support. As a face developer, we recommend you treat custom messages as 'best effort' since your face will never know if the custom message is supported by the underlying viewer. It is therefore important to make affordances for this in your Web face's UI.

BLOCKv

All BLOCKv vAtoms apps support the following face messages:

Custom Viewer

If you are a Viewer developer, it is up to you to add support for custom face messages. The table above lists those custom messages most Web faces will expect your app to support.