# @zappar/sharing

> This module allows you to easily save & share snapshots or videos of a WebGL canvas.

Latest version **1.1.7** (published 2022-05-25) · Proprietary license · 16 weekly downloads

## Install

```sh
npm install @zappar/sharing
pnpm add @zappar/sharing
yarn add @zappar/sharing
bun add @zappar/sharing
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.7 |
| Published | 2022-05-25 |
| First published | 2021-12-14 |
| Weekly downloads | 16 |
| License | Proprietary |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 50.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Zappar Limited |
| Maintainers | alex-dg, cgauld, deim, simon_zappar, jordan-zappar, george.martin, emmaford, janders, squeral, francesca.may, justin_zappar |
| Keywords | webgl, screenshot, canvas, zappar, UAR, AR, WebAR, screencap, camera, webshare, navigator.share |

## Links

- npm: https://www.npmjs.com/package/@zappar/sharing
- npm.io page: https://npm.io/package/@zappar/sharing

## Dependencies (2)

- [csstype](https://npm.io/package/csstype.md) ^3.0.5
- [ua-parser-js](https://npm.io/package/ua-parser-js.md) ^0.7.28

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 1.1.7 (latest) — 2022-05-25
- 1.1.6 — 2022-05-25
- 1.1.5 — 2022-05-06
- 1.1.4 — 2022-05-06
- 1.1.3 — 2022-01-20
- 1.1.2 — 2021-12-14

## README

# Zappar 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.
​

> <i class="fa fa-info-circle"></i> You may also be interested in:
>
> - [Zappar for ThreeJS](https://www.npmjs.com/package/@zappar/zappar-threejs) (@zappar/zappar-threejs)
> - [Zappar for AFrame](https://www.npmjs.com/package/@zappar/zappar-aframe) (@zappar/zappar-aframe)
> - Zappar's library for Unity
> - [Zappar for JavaScript](https://www.npmjs.com/package/@zappar/zappar) (@zappar/zappar), if you'd like to build content with a different 3D rendering platform
> - ZapWorks Studio, a full 3D development environment built for AR, VR and MR

## Table Of Contents

<!--ts-->
   * [Zappar Sharing](#zappar-sharing)
      * [Table Of Contents](#table-of-contents)
      * [Starting Development](#starting-development)
      * [Installation](#installation)
      * [Usage](#usage)
         * [Importing](#importing)
         * [Capturing the Canvas](#capturing-the-canvas)
            * [Recording the canvas](#recording-the-canvas)
         * [Getting Callbacks from the Save &amp; Share Dialog](#getting-callbacks-from-the-save--share-dialog)
         * [Customization](#customization)
      * [Editing Pre-Defined Styles](#editing-pre-defined-styles)
      * [Localizations](#localizations)
      * [Example](#example)

<!-- Added by: zapparadmin, at: Wed May 25 13:04:03 BST 2022 -->

<!--te-->

## Starting Development

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

## Installation

​
**Using NPM**

​
Run the following NPM command inside your project directory:
​

```bash
npm install @zappar/sharing
```

​
**CDN**

​
Reference `zappar-sharing.min.js` from your HTML like this:
​

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

​

## Usage

### Importing

Import the library into your JavaScript or TypeScript files:

 ```ts
 import ZapparSharing from '@zappar/sharing';
 ```

### Capturing the Canvas

><i class="fa fa-info-circle"></i> This should be done **after** WebGL renders a frame or with​ `preserveDrawingBuffer` enabled.

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

 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./tests/readme_examples.ts&block=capturing-the-canvas) -->
 <!-- The below code snippet is automatically added from ./tests/readme_examples.ts -->
 ```ts
 // 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,
 });
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->

#### Recording the canvas

You may use `@zappar/video-recorder` for video recording.

```ts
import * as ZapparVideoRecorder from '@zappar/video-recorder';

// ...

const canvas = document.querySelector('canvas');

const recorder = await ZapparVideoRecorder.createCanvasVideoRecorder(canvas, {
  quality: 25,
  speed: 10,
  halfSample: true,
});

recordButton.addEventListener('click', () => {
  recorder.start();
});

stopRecordButton.addEventListener('click', () => {
  recorder.stop();
});

recorder.onComplete.bind(async (res) => {
  ZapparSharing({
    data: await res.asDataURL(),
  });
});
```

There are patent licensing implications to the use and deployment of the recorder package. Find out more about licensing and the usage over at <https://www.npmjs.com/package/@zappar/video-recorder>.

### Getting Callbacks from the Save & Share Dialog

 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./tests/readme_examples.ts&block=getting-callbacks) -->
 <!-- The below code snippet is automatically added from ./tests/readme_examples.ts -->
 ```ts
 // ...
 ZapparSharing({
   data: url,
   onSave: () => {
     console.log('Image was saved');
   },
   onShare: () => {
     console.log('Share button was pressed');
   },
   onClose: () => {
     console.log('Dialog was closed');
   },
 });
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->


> <i class="fa fa-info-circle"></i> 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

​


 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./tests/readme_examples.ts&block=customization) -->
 <!-- The below code snippet is automatically added from ./tests/readme_examples.ts -->
 ```ts
 // ...
 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.
 });
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->

## 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.

 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./tests/readme_examples.ts&block=pre-defined-styles) -->
 <!-- The below code snippet is automatically added from ./tests/readme_examples.ts -->
 ```ts
 ZapparSharing({
   data: url,
   hideShareButton: true,
 }, {
   buttonCloseAnchor: {
     width: '15px',
     height: '15px',
   },
 });
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->


<details>
  <summary>Default Style Reference</summary>

 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./src/styles.ts&block=styles) -->
 <!-- The below code snippet is automatically added from ./src/styles.ts -->
 ```ts
   saveShareAnchor: {
     display: 'flex',
     width: '70px',
     height: '70px',
     marginTop: '2.5%',
     marginLeft: '5%',
     marginRight: '5%',
   },
   buttonImage: {
     pointerEvents: 'none',
     display: 'flex',
     justifyContent: 'center',
     margin: 'auto',
     width: '40px',
     height: '40px',
   },
   buttonCloseAnchor: {
     width: '15px',
     height: '15px',
     margin: '4%',
     zIndex: 9999,
     top: 0,
     position: 'absolute',
   },
   previewElement: {
     height: 'auto',
     width: '80%',
     marginLeft: 'auto',
     marginRight: 'auto',
     backgroundColor: '#ccc',
     boxShadow: '0px 0px 4px 0px rgba(0,0,0,0.5)',
     display: 'flex',
   },
   containerDiv: {
     position: 'fixed',
     width: '100%',
     height: '100%',
     top: '0px',
     left: '0px',
     zIndex: 10000,
     backgroundColor: 'rgba(255,255,255,1)',
     fontFamily: 'sans-serif',
     color: 'rgba(255,255,255,1)',
     display: 'flex',
     flexDirection: 'column',
     justifyContent: 'center',
   },
   flexContainerDiv: {
     display: 'flex',
     justifyContent: 'center',
     flexWrap: 'wrap',
   },
   buttonCloseImage: {
     pointerEvents: 'none',
     width: '15px',
     height: '15px',
   },
   buttonOpenFiles: {
     border: '2px solid black',
     textTransform: 'uppercase',
     padding: '10px',
     minWidth: '50px',
     color: 'black',
     display: 'inline - block',
     marginTop: '20px',
     textDecoration: 'none',
     borderRadius: '10px',
     paddingTop: '15px',
   },
   instructions: {
     color: 'black',
     marginBottom: '0',
     width: '100%',
     textAlign: 'center',
     display: 'none',
   },
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->

</details>

## Localizations

Custom text or localizations can be implemented:

 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./tests/readme_examples.ts&block=localizations) -->
 <!-- The below code snippet is automatically added from ./tests/readme_examples.ts -->
 ```ts
 // ...
 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',
 });
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->

## Example

​
Using the snippets above, your script should now include:
​

 <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./tests/readme_examples.ts&block=full-example) -->
 <!-- The below code snippet is automatically added from ./tests/readme_examples.ts -->
 ```ts
 // 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',
 });
 ```
 <!-- AUTO-GENERATED-CONTENT:END -->

---
_Source: https://npm.io/package/@zappar/sharing · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._