diff --git a/examples/selfie/README.md b/examples/selfie/README.md index e5f491db9..c24cb54ea 100644 --- a/examples/selfie/README.md +++ b/examples/selfie/README.md @@ -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 + +- [Miro Web SDK](https://developers.miro.com/docs/web-sdk-reference) +- [Custom Actions](https://developers.miro.com/docs/action_customactionmanagement) + +# 🛠ī¸ Tools and Technologies + +- [React](https://react.dev/) +- [TypeScript](https://www.typescriptlang.org/) +- [Vite](https://vitejs.dev/) + +# ✅ Prerequisites -- 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 -- 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 - +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. In the video we install a different app, but the process is the same regardless of the app. + +> ⚠ī¸ 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 ``` . ├── 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 - +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 -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).