-
Notifications
You must be signed in to change notification settings - Fork 210
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
78 additions
and
35 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,54 +1,97 @@ | ||
| ## Self Image | ||
| # Miro Selfie | ||
|
|
||
| ** ℹ Note**: | ||
| The app examples demonstrates how you can leverage Miro SDK to take selfies using the browser API and easily update them by using Custom actions. | ||
|
|
||
| - We recommend a Chromium-based web browser for local development with HTTP. \ | ||
| Safari enforces HTTPS; therefore, it doesn't allow localhost through HTTP. | ||
| - For more information, visit our [developer documentation](https://developers.miro.com). | ||
| ℹ️ **Important**: Custom actions are only supported for non-public apps that will be distributed privately via a shareable authorization link from your App Settings page. This means that apps built with custom actions will not be eligible for distribution via the Miro Marketplace. | ||
|
|
||
| ### How to start locally | ||
| # 👨🏻💻 App Demo | ||
|
|
||
| - Run `npm i` to install dependencies. | ||
| - Run `npm start` to start developing. \ | ||
| Your URL should be similar to this example: | ||
| # 📒 Table of Contents | ||
|
|
||
| ``` | ||
| http://localhost:3000 | ||
| ``` | ||
| - [Included Features](#features) | ||
| - [Tools and Technologies](#tools) | ||
| - [Prerequisites](#prerequisites) | ||
| - [Associated Developer Tutorial](#tutorial) | ||
| - [Run the app locally](#run) | ||
| - [Folder Structure](#folder) | ||
| - [License](#license) | ||
|
|
||
| # ⚙️ Included Features <a name="features"></a> | ||
|
|
||
| - [Miro Web SDK](https://developers.miro.com/docs/web-sdk-reference) | ||
| - [Custom Actions](https://developers.miro.com/docs/action_customactionmanagement) | ||
|
|
||
| # 🛠️ Tools and Technologies <a name="tools"></a> | ||
|
|
||
| - [React](https://react.dev/) | ||
| - [TypeScript](https://www.typescriptlang.org/) | ||
| - [Vite](https://vitejs.dev/) | ||
|
|
||
| # ✅ Prerequisites <a name="prerequisites"></a> | ||
|
|
||
| - Paste the URL under **App URL** in your | ||
| [app settings](https://developers.miro.com/docs/build-your-first-hello-world-app#step-3-configure-your-app-in-miro). | ||
| - Open a board; you should see your app in the app toolbar or in the **Apps** | ||
| panel. | ||
| - You have a [Miro account](https://miro.com/signup/). | ||
| - You're [signed in to Miro](https://miro.com/login/). | ||
| - Your Miro account has a [Developer team](https://developers.miro.com/docs/create-a-developer-team). | ||
| - Your development environment includes [Node.js 14.13](https://nodejs.org/en/download) or a later version. | ||
| - All examples use `npm` as a package manager and `npx` as a package runner. | ||
| - Your app is a private app, and it's **not** publicly available on the [Miro Marketplace](https://miro.com/marketplace). | ||
| Currently, custom actions are available only for private apps. | ||
|
|
||
| ### How to build the app | ||
| # 📖 Associated Developer Tutorial <a name="tutorial"></a> | ||
|
|
||
| - Run `npm run build`. \ | ||
| This generates a static output inside [`dist/`](./dist), which you can host on a static hosting | ||
| service. | ||
| > To view a more in depth developer tutorial | ||
| > of this app (including code explanations) see the [custom actions tutorial](https://developers.miro.com/docs/add-custom-actions-to-your-app) on Miro's Developer documentation. | ||
| ### Folder structure | ||
| # 🏃🏽♂️ Run the app locally <a name="run"></a> | ||
|
|
||
| <!-- The following tree structure is just an example --> | ||
| 1. Run `npm install` to install dependencies. | ||
| 2. Run `npm start` to start developing. \ | ||
| Your URL should be similar to this example: | ||
| ``` | ||
| http://localhost:3000 | ||
| ``` | ||
| 3. Open the [app manifest editor](https://developers.miro.com/docs/manually-create-an-app#step-2-configure-your-app-in-miro) by clicking **Edit in Manifest**. \ | ||
| In the app manifest editor, configure the app as follows: | ||
|
|
||
| - [`sdkUri`](https://developers.miro.com/docs/app-manifest#sdkuri): assign `http://localhost:3000` as a value for this property. \ | ||
| It defines the entry point of the app, and it corresponds to the URL of the server that the app runs on. | ||
| - [`scopes`](https://developers.miro.com/docs/app-manifest#scopes): add the permission scopes that users need to grant the app when they install it. \ | ||
| To enable the app to read from and write to the board, add the following permissions: | ||
| - `boards:read` | ||
| - `boards:write` | ||
| - `webcam:record` | ||
|
|
||
| 4. Go back to your app home page, and under the `Permissions` section, you will see a blue button that says `Install app and get OAuth token`. Click that button. Then click on `Add` as shown in the video below. <b>In the video we install a different app, but the process is the same regardless of the app.</b> | ||
|
|
||
| > ⚠️ We recommend to install your app on a [developer team](https://developers.miro.com/docs/create-a-developer-team) while you are developing or testing apps.⚠️ | ||
| https://github.com/miroapp/app-examples/assets/10428517/1e6862de-8617-46ef-b265-97ff1cbfe8bf | ||
|
|
||
| 5. Go to your developer team, and open your boards. | ||
| 6. Click on the app icon on the left sidebar. | ||
| 7. On the modal that appears, click on the `Capture` button. | ||
| 8. An image item with your picture should appear in the board. | ||
| 9. Once you click on the image in the board, from the context menu that appears, click on the plus icon. If you hover over it, it will say `App actions`. | ||
| 10. Select a custom action to either take another selfie or update the existing one in place. | ||
| 11. You can select other images in the board that are not created from this app, they should not have the custom actions. | ||
|
|
||
| # 🗂️ Folder structure <a name="folder"></a> | ||
|
|
||
| ``` | ||
| . | ||
| ├── src | ||
| │ ├── assets | ||
| │ │ └── style.css | ||
| │ ├── app.tsx // The code for the app lives here | ||
| │ └── index.ts // The code for the app entry point lives here | ||
| ├── app.html // The app itself. It's loaded on the board inside the 'appContainer' | ||
| └── index.html // The app entry point. This is what you specify in the 'App URL' box in the Miro app settings | ||
| │ └── index.tsx <-- Where the custom actions and icon click handler are defined. | ||
| │ └── app.tsx <-- Where the selfie is taken and the image created/updated | ||
| ├── tsconfig.json <-- typescript configuration file | ||
| ├── vite.config.ts <-- Vite configuration file | ||
| └── index.html <-- The app entry point. This is the value you assign to 'sdkUri' in the app manifest file. | ||
| └── capture.html <-- The content displayed in the modal to capture your selfie. | ||
| ``` | ||
|
|
||
| ### About the app | ||
|
|
||
| This sample app provides you with boilerplate setup and configuration that you can further customize to build your own app. | ||
| # 🫱🏻🫲🏽 Contributing <a name="contributing"></a> | ||
|
|
||
| <!-- describe shortly the purpose of the sample app --> | ||
| If you want to contribute to this example, or any other Miro Open Source project, please review [Miro's contributing guide](https://github.com/miroapp/app-examples/blob/main/CONTRIBUTING.md). | ||
|
|
||
| Built using [`create-miro-app`](https://www.npmjs.com/package/create-miro-app). | ||
| # 🪪 License <a name="license"></a> | ||
|
|
||
| This app uses [Vite](https://vitejs.dev/). \ | ||
| If you want to modify the `vite.config.js` configuration, see the [Vite documentation](https://vitejs.dev/guide/). | ||
| [MIT License](https://github.com/miroapp/app-examples/blob/main/LICENSE). |