BLOCKv Developer Platform

BLOCKv Basics

vAtom

Ecosystem Roles

Template and Variation

Action

Face

Building vAtoms

Overview

Guidelines

Configuring Faces

Image

Image Progress

Image Policy

Image Layered

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:

Method	Description	Restrictions
`init()`	Initializes the bridge.
`userManager.getPublicUser(userID)`	Fetches the publicly available information for the specified user identifier.	Only publicly visible information is returned.
`vatomManager.getVatom(vatomID)`	Fetches the vAtom payload for the specified vAtom id.	Permitted for the backing vAtom or one of it's first-level children.
`vatomManager.getChildren(vatomID)`	Fetches the vAtom payload for this first-level children of the specified vAtom.	Only permitted on the backing vAtom.
`vatomManager.performAction(actionName, payload)`	Performs an action on vAtom	Only permitted on the backing vAtom.
`resourceManager.encodeResource([urls])`	Encodes (if needed) with access credentials.	Any resource may be encoded.

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:

Method	Description
`viewer.vatom.show`	Request the viewer to engage the specified vAtom.
`viewer.map.show`	Request the viewer to shows its map UI.
`viewer.qr.scan`	Request the viewer to show a QR scanner and passes back the response to the web app.
`viewer.view.close`	Request the viewer to close the current vAtom.
`viewer.scanner.show`	Request the viewer to open a scanner and to interpret the scan result itself.
`viewer.card.show`	Request the viewer to show the card view mode.

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.

Info