WebGL Sharing

This package allows you to easily implement a snapshot or video save/share functionality into your WebGL applications. It includes the ability to save the result and, where available, the native Web Share API makes it possible to social share to other apps installed on the device.

This is used as an addition to projects set up with the Zappar camera and a chosen tracking type.

Installation

You can use this library by linking to our CDN, or by installing from NPM for use in a webpack project.

Using NPM

Run the following NPM command inside your project directory:

npm install @zappar/sharing

CDN

Reference zappar-snapshot.min.js from your HTML like this:

<script src="https://libs.zappar.com/zappar-sharing/*/zappar-sharing.min.js"></script>

* Version number can be found on the package's dedicated NPM page

Usage

Importing

Import the library into your JavaScript or TypeScript files:

import ZapparSharing from '@zappar/sharing';

Capturing the Canvas

Add this snippet into the event in which you would like the Save & Share Dialog to appear:

// Get canvas from dom
const canvas = document.querySelector('canvas');
// Convert canvas data to url
const url = canvas!.toDataURL('image/jpeg', 0.8);
// Take snapshot
ZapparSharing({
  data: url,
});

Capturing the canvas should be done after WebGL renders a frame or with preserveDrawingBuffer enabled.

Callbacks

Getting Callbacks from the Save & Share Dialog

// ...
ZapparSharing({
  data: url,
  onSave: () => {
    console.log('Image was saved');
  },
  onShare: () => {
    console.log('Share button was pressed');
  },
  onClose: () => {
    console.log('Dialog was closed');
  },
});

The arguments indicate if the user tapped on the Save or Share buttons in that dialog, but do not guarantee that the user actually completed those actions. onClose is called when the user returns from the Save/Share dialog.

Customization

The following snippet shows how you can customize things like, the file name, the title, text and URL:

// ...
ZapparSharing({
  data: url,
  fileNamePrepend: 'Zappar', // The name of  the file.
  shareTitle: 'Hello World!', // The title for the social share.
  shareText: 'Hello World!', // The body text for the social share.
  shareUrl: 'www.zappar.com', // The url for the social share.
  hideShareButton: true, // Hide the share button.
});

Editing Pre-Defined Styles

The package comes with a pre-defined style which you can override.

This can be done by passing a style object as a parameter as seen in the example.

ZapparSharing({
  data: url,
  hideShareButton: true,
}, {
  buttonCloseAnchor: {
    width: '15px',
    height: '15px',
  },
});

Find the default style reference on the package's dedicated NPM page

Localizations

Custom text or localizations can be implemented:

// ...
ZapparSharing({
  data: url,
  hideShareButton: true,
}, {}, {
  SAVE: 'SAVE',
  SHARE: 'SHARE',
  NowOpenFilesAppToShare: 'Now open files app to share',
  TapAndHoldToSave: 'Tap and hold the image<br/>to save to your Photos app',
});

Example

Using the snippets above, your script should now include:

// Get canvas from dom
const canvas = document.querySelector('canvas');

// Convert canvas data to url

const url = canvas!.toDataURL('image/jpeg', 0.8);

ZapparSharing({
  data: url,
  fileNamePrepend: 'Zappar',
  shareUrl: 'www.zappar.com',
  shareTitle: 'Hello World!',
  shareText: 'Hello World!',
  onSave: () => {
    console.log('Image was saved');
  },
  onShare: () => {
    console.log('Share button was pressed');
  },
  onClose: () => {
    console.log('Dialog was closed');
  },
}, {}, {
  SAVE: 'SAVE',
  SHARE: 'SHARE',
  NowOpenFilesAppToShare: 'Now open files app to share',
  TapAndHoldToSave: 'Tap and hold the image<br/>to save to your Photos app',
});

Caveats

The Save and Share User Flow

The user flow for this package's save and share options will differ depending on the device. This is because the package uses the browser’s default Web Share API handler.

Android

Android users will see both the Save and Share button side by side.

iOS

iOS 14 and older users must first Save their image and then click on the Open Files App button in order to open their device's 'Files' application. They will then be able to share their snapshot from their native device.

iOS 15 makes this much easier and allows for sharing directly in the user flow.

If you would like to implement a different WebShare API, then you will have to do this yourself.