diff --git a/.gitignore b/.gitignore index a6ed8658..0500d8a1 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,9 @@ .docusaurus .cache-loader /docs/js-sdk/api +/docs/js-sdk/examples/quickstart/*.ts +/docs/js-sdk/examples/view-manifest/*.ts +/docs/js-sdk/examples/view-manifest/*.html /docs/c2patool/*.md /docs/c2patool/docs/*.md /docs/c2pa-node/*.md diff --git a/docs/js-sdk/examples/.gitkeep b/docs/js-sdk/examples/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/js-sdk/examples/quickstart/.gitkeep b/docs/js-sdk/examples/quickstart/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/js-sdk/examples/view-manifest/.gitkeep b/docs/js-sdk/examples/view-manifest/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/js-sdk/getting-started/overview.mdx b/docs/js-sdk/getting-started/overview.mdx index b5ad0226..dd3490d1 100644 --- a/docs/js-sdk/getting-started/overview.mdx +++ b/docs/js-sdk/getting-started/overview.mdx @@ -25,8 +25,7 @@ The JavaScript library uses several modern browser technologies, including: The JavaScript library is a monorepo containing the following packages intended for client use: -- [**c2pa**](https://opensource.contentauthenticity.org/docs/js-sdk/api/c2pa) is the main package used for loading and verifying manifests. This package runs all of the processing - logic on the client using a [WebAssembly](https://webassembly.org/) module and exposes a [TypeScript](https://www.typescriptlang.org/)-compatible API for easy integration. +- [**c2pa**](https://opensource.contentauthenticity.org/docs/js-sdk/api/c2pa) is the main package used for loading and verifying manifests. This package runs all of the processing logic on the client using a [WebAssembly](https://webassembly.org/) module and exposes a [TypeScript](https://www.typescriptlang.org/)-compatible API for easy integration. - **c2pa-wc** provides UI components designed with input from the C2PA UX working group. It enables users to get up and running with standard UI patterns quickly and easily in any front-end environment. - **@contentauth/react** provides a hooks interface for React components to quickly get manifest and thumbnail data in your React app. @@ -59,7 +58,7 @@ Because of these requirements, **the library is not supported on any version of ![CAI JavaScript library browser support](../../../static/img/caniuse.png) :::info -This chart is accurate as of June, 2024. For the most up-to-date browser support information, see [caniuse.com](https://caniuse.com/wasm,webworkers,cryptography,typedarrays,fetch). +This chart is accurate as of December, 2024. For the most up-to-date browser support information, see [caniuse.com](https://caniuse.com/wasm,webworkers,cryptography,typedarrays,fetch). ::: ## Debugging @@ -72,7 +71,7 @@ To view debug messages in the console, use your browser's inspector, go to the C localStorage.debug = 'c2pa:*'; ``` -The debuging information includes millisecond timing differences so you can get an idea of how long different events take. +The debugging information includes millisecond timing differences so you can get an idea of how long different events take. :::note Debug calls and statements are stripped out of minified production builds to reduce file size. diff --git a/docs/js-sdk/getting-started/quick-start.mdx b/docs/js-sdk/getting-started/quick-start.mdx index aa1d22ec..af38dcf9 100644 --- a/docs/js-sdk/getting-started/quick-start.mdx +++ b/docs/js-sdk/getting-started/quick-start.mdx @@ -5,7 +5,6 @@ title: Quick start import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -import Sandbox from '../../../src/components/Sandbox'; ## Prerequisites @@ -37,6 +36,7 @@ The quickest way to get up and running is to use a CDN such as [jsDelivr](https: Static assets include the following, as seen in the config passed to [`createC2pa`](../../js-sdk/api/c2pa.createc2pa): ```js +const version = '0.24.2'; { wasmSrc: `https://cdn.jsdelivr.net/npm/c2pa@${version}/dist/assets/wasm/toolkit_bg.wasm`, workerSrc: `https://cdn.jsdelivr.net/npm/c2pa@${version}/dist/c2pa.worker.min.js`, @@ -44,12 +44,9 @@ Static assets include the following, as seen in the config passed to [`createC2p ``` :::caution -The version numbers provided in the CDN URLs _must_ match in all of the places you reference the -library. To make it easy, use a variable that provides the version as shown in the example. +The version numbers provided in the CDN URLs _must_ be the same in all of the places you reference the library. To make it easy, use a variable that provides the version as shown in the example. ::: - - ### Using a package manager You can also bring in the library with a package manager, such as `npm`, `pnpm`, or `yarn`. This way, all of the client side code is hosted with your app and there are no external dependencies. For example, using `npm`: @@ -71,24 +68,30 @@ Be sure to configure your server to send proper `Content-Type` headers for these Examples for common build systems are shown below. They are also available in the [c2pa-js-examples repository](https://github.com/contentauth/c2pa-js-examples). -export const ExampleLink = ({ example }) => { - const linkText = `examples/${example}`; - const link = `https://github.com/contentauth/c2pa-js/tree/main/${linkText}`; - return ( -
- An example project is available here: {linkText} -
- ); -}; +import CodeBlock from '@theme/CodeBlock'; +import ViteExample from '!!raw-loader!../examples/quickstart/vite-main.ts'; +import RollupExample from '!!raw-loader!../examples/quickstart/rollup-main.ts'; +import WebPackExample from '!!raw-loader!../examples/quickstart/webpack-main.ts'; - - - - - - - - - + + +This example is from [c2pa-js-examples/minimal-ts-vite/](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-vite/). To view and execute this example in a live [code sandbox](https://codesandbox.io/docs/learn/legacy-sandboxes/overview), see [Code Sandbox: Vite example](../guides/sandbox-qs-vite.mdx). + +{ViteExample} + + + + +This example is from [c2pa-js-examples/minimal-ts-rollup/](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-rollup/). To view and execute this example in a live [code sandbox](https://codesandbox.io/docs/learn/legacy-sandboxes/overview), see [Code Sandbox: Rollup example](../guides/sandbox-qs-rollup.mdx). + +{RollupExample} + + + + +This example is from [c2pa-js-examples/minimal-ts-webpack/](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-webpack/). To view and execute this example in a live [code sandbox](https://codesandbox.io/docs/learn/legacy-sandboxes/overview), see [Code Sandbox: Webpack example](../guides/sandbox-qs-webpack.mdx). + +{WebPackExample} + diff --git a/docs/js-sdk/guides/hosting.mdx b/docs/js-sdk/guides/hosting.mdx index 46fb22be..18501eec 100644 --- a/docs/js-sdk/guides/hosting.mdx +++ b/docs/js-sdk/guides/hosting.mdx @@ -42,7 +42,7 @@ examples of configuring popular build systems, see the [Quick start guide](../ge To host the library yourself, expose the static asset files with the following response headers to avoid errors with some browsers: -- `c2pa/dist/assets/wasm/toolkit_bg.wasm`: Serve with `Content-Type: application/wasm` reponse header. +- `c2pa/dist/assets/wasm/toolkit_bg.wasm`: Serve with `Content-Type: application/wasm` response header. - `c2pa/dist/c2pa.worker.min.js`: Serve with `Content-Type: text/javascript` response header. Then pass these URLs to the `createC2pa` function; for example: diff --git a/docs/js-sdk/guides/sandbox-qs-rollup.mdx b/docs/js-sdk/guides/sandbox-qs-rollup.mdx new file mode 100644 index 00000000..df76eef9 --- /dev/null +++ b/docs/js-sdk/guides/sandbox-qs-rollup.mdx @@ -0,0 +1,11 @@ +--- +id: sandbox-rollup +title: 'Code Sandbox: Rollup example' +hide_table_of_contents: true +--- + +import Sandbox from '../../../src/components/Sandbox'; + +The source code for this example is in the [c2pa-js-examples repo](https://github.com/contentauth/c2pa-js-examples/tree/main/minimal-ts-rollup). + + diff --git a/docs/js-sdk/guides/sandbox-qs-vite.mdx b/docs/js-sdk/guides/sandbox-qs-vite.mdx new file mode 100644 index 00000000..da1585e4 --- /dev/null +++ b/docs/js-sdk/guides/sandbox-qs-vite.mdx @@ -0,0 +1,11 @@ +--- +id: sandbox-vite +title: 'Code Sandbox: Vite example' +hide_table_of_contents: true +--- + +import Sandbox from '../../../src/components/Sandbox'; + +The source code for this example is in the [c2pa-js-examples repo](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-vite/). + + diff --git a/docs/js-sdk/guides/sandbox-qs-webpack.mdx b/docs/js-sdk/guides/sandbox-qs-webpack.mdx new file mode 100644 index 00000000..f8d04e93 --- /dev/null +++ b/docs/js-sdk/guides/sandbox-qs-webpack.mdx @@ -0,0 +1,11 @@ +--- +id: sandbox-webpack +title: 'Code Sandbox: Webpack example' +hide_table_of_contents: true +--- + +import Sandbox from '../../../src/components/Sandbox'; + +The source code for this example is in the [c2pa-js-examples repo](https://github.com/contentauth/c2pa-js-examples/tree/main/minimal-ts-webpack). + + diff --git a/docs/js-sdk/guides/sandbox-view-manifest.mdx b/docs/js-sdk/guides/sandbox-view-manifest.mdx new file mode 100644 index 00000000..fccba89f --- /dev/null +++ b/docs/js-sdk/guides/sandbox-view-manifest.mdx @@ -0,0 +1,11 @@ +--- +id: sandbox-viewing-manifest +title: 'Code Sandbox: Viewing manifest data' +hide_table_of_contents: true +--- + +import Sandbox from '../../../src/components/Sandbox'; + +The source code for this example is in the [c2pa-js-examples repo](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-vite/examples/active-manifest/main.ts). + + diff --git a/docs/js-sdk/guides/viewing-provenance.mdx b/docs/js-sdk/guides/viewing-provenance.mdx index 0b5ca0ce..d14d2f91 100644 --- a/docs/js-sdk/guides/viewing-provenance.mdx +++ b/docs/js-sdk/guides/viewing-provenance.mdx @@ -1,11 +1,8 @@ --- id: viewing-manifest-data title: Viewing manifest data -hide_table_of_contents: true --- -import Sandbox from '../../../src/components/Sandbox'; - ## Initializing the library The way that you import `wasmSrc` and `workerSrc` varies depending on the build system you use. For more information, see [Quick start](../getting-started/quick-start#bringing-in-the-library). @@ -20,10 +17,32 @@ The [`manifestStore`](../../js-sdk/api/c2pa.c2pareadresult.manifeststore) object - **activeManifest**: A pointer to the latest [`manifest`](../../js-sdk/api/c2pa.manifest) in the manifest store. Effectively the "parent" manifest, this is the likely starting point when inspecting an asset's C2PA data. - **validationStatus**: A list of any validation errors the library generated when processing an asset. See [Validation](./validation) for more information. -[`Manifest`](../../js-sdk/api/c2pa.manifest) objects contain properties pertaining to an asset's provenance, along with convenient interfaces for [accessing assertion data](../../js-sdk/api/c2pa.assertionaccessor) and [generating a thumbnail](../../js-sdk/api/c2pa.thumbnail). The example in this sandbox demonstrates a basic workflow: reading a sample image, checking for the presence of a manifest store, and displaying the data in the active manifest: +[`Manifest`](../../js-sdk/api/c2pa.manifest) objects contain properties pertaining to an asset's provenance, along with convenient interfaces for [accessing assertion data](../../js-sdk/api/c2pa.assertionaccessor) and [generating a thumbnail](../../js-sdk/api/c2pa.thumbnail). + +## Example - +This example from the [c2pa-js-examples repo](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-vite/examples/active-manifest/) demonstrates a basic workflow: -The source code for this example is in the [c2pa-js-examples repo](https://github.com/contentauth/c2pa-js-examples/blob/main/minimal-ts-vite/examples/active-manifest/main.ts). +- Reading an image. +- Checking for the presence of a manifest store. +- Displaying the data in the active manifest. This example also features the use of the [`selectProducer`](../../js-sdk/api/c2pa.selectproducer) selector function. See [Selectors](./selectors) for more information. + +To view and execute this example in a live [code sandbox](https://codesandbox.io/docs/learn/legacy-sandboxes/overview), see [Sandbox: Viewing manifest data](./sandbox-viewing-manifest). + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +import CodeBlock from '@theme/CodeBlock'; +import ViewManifestExampleTS from '!!raw-loader!../examples/view-manifest/main.ts'; +import ViewManifestExampleHTML from '!!raw-loader!../examples/view-manifest/index.html'; + + + + {ViewManifestExampleTS} + + + {ViewManifestExampleHTML} + + diff --git a/scripts/fetch-readme.js b/scripts/fetch-readme.js index de000378..feccdc4e 100644 --- a/scripts/fetch-readme.js +++ b/scripts/fetch-readme.js @@ -19,6 +19,45 @@ $ touch .gitkeep */ const readmes = [ + // js-sdk examples - View manifest + { + dest: resolve( + __dirname, + '../docs/js-sdk/examples/view-manifest/index.html', + ), + repo: 'contentauth/c2pa-js', + path: 'examples/minimal-ts-vite/examples/active-manifest/index.html', + }, + { + dest: resolve(__dirname, '../docs/js-sdk/examples/view-manifest/main.ts'), + repo: 'contentauth/c2pa-js', + path: 'examples/minimal-ts-vite/examples/active-manifest/main.ts', + }, + // Vite Quickstart + { + dest: resolve(__dirname, '../docs/js-sdk/examples/quickstart/vite-main.ts'), + repo: 'contentauth/c2pa-js', + path: 'examples/minimal-ts-vite/examples/cdn/main.ts', + }, + // Rollup Quickstart + { + dest: resolve( + __dirname, + '../docs/js-sdk/examples/quickstart/rollup-main.ts', + ), + repo: 'contentauth/c2pa-js', + path: 'examples/minimal-ts-rollup/src/main.ts', + }, + // WebPack Quickstart + { + dest: resolve( + __dirname, + '../docs/js-sdk/examples/quickstart/webpack-main.ts', + ), + repo: 'contentauth/c2pa-js', + path: 'examples/minimal-ts-webpack/src/index.ts', + }, + // c2patool { dest: resolve(__dirname, '../docs/c2patool/readme.md'), diff --git a/static/img/caniuse.png b/static/img/caniuse.png index a3c305b8..f670ab97 100644 Binary files a/static/img/caniuse.png and b/static/img/caniuse.png differ