diff --git a/assets/fill-domain-into-configuration.png b/assets/fill-domain-into-configuration.png new file mode 100644 index 000000000..f188a3084 Binary files /dev/null and b/assets/fill-domain-into-configuration.png differ diff --git a/assets/setup-domain-for-sales-channel-DSR.png b/assets/setup-domain-for-sales-channel-DSR.png index 6979f607e..fd21327cf 100644 Binary files a/assets/setup-domain-for-sales-channel-DSR.png and b/assets/setup-domain-for-sales-channel-DSR.png differ diff --git a/products/digital-sales-rooms/app-deployment/cloudflare.md b/products/digital-sales-rooms/best-practices/app-deployment/cloudflare.md similarity index 97% rename from products/digital-sales-rooms/app-deployment/cloudflare.md rename to products/digital-sales-rooms/best-practices/app-deployment/cloudflare.md index da00fe2ea..6f667951b 100644 --- a/products/digital-sales-rooms/app-deployment/cloudflare.md +++ b/products/digital-sales-rooms/best-practices/app-deployment/cloudflare.md @@ -30,7 +30,7 @@ strict-peer-dependencies=false pnpm install wrangler --save-dev ``` -- Make sure the Frontend app has already [generated .env file](../local-installation/app-installation.md#generate-env-file) +- Make sure the Frontend app has already [generated .env file](../../installation/app-installation.md#generate-env-file) - Build your project for Cloudflare Pages: @@ -123,4 +123,4 @@ When deploying your Pages project, you may wish to point custom domains (or subd ## Configure sales channel domain -Your website is ready, you should have a frontend app domain. Please use the current domain to configure [sales channel domain](../configuration/domain-config.md). +Your website is ready, you should have a frontend app domain. Please use the current domain to configure [sales channel domain](../../configuration/domain-config.md). diff --git a/products/digital-sales-rooms/app-deployment/index.md b/products/digital-sales-rooms/best-practices/app-deployment/index.md similarity index 97% rename from products/digital-sales-rooms/app-deployment/index.md rename to products/digital-sales-rooms/best-practices/app-deployment/index.md index 2234f03ee..a373e038e 100644 --- a/products/digital-sales-rooms/app-deployment/index.md +++ b/products/digital-sales-rooms/best-practices/app-deployment/index.md @@ -1,7 +1,7 @@ --- nav: title: Frontend App Deployment - position: 40 + position: 10 --- diff --git a/products/digital-sales-rooms/best-practices/index.md b/products/digital-sales-rooms/best-practices/index.md new file mode 100644 index 000000000..5c0826a6d --- /dev/null +++ b/products/digital-sales-rooms/best-practices/index.md @@ -0,0 +1,6 @@ +--- +nav: + title: Best practices + position: 40 + +--- diff --git a/products/digital-sales-rooms/saas/index.md b/products/digital-sales-rooms/best-practices/saas/index.md similarity index 79% rename from products/digital-sales-rooms/saas/index.md rename to products/digital-sales-rooms/best-practices/saas/index.md index 3116a06e0..3cab7102e 100644 --- a/products/digital-sales-rooms/saas/index.md +++ b/products/digital-sales-rooms/best-practices/saas/index.md @@ -1,7 +1,7 @@ --- nav: title: SaaS - position: 50 + position: 20 --- @@ -12,6 +12,6 @@ However, there are some steps that need to be completed to ensure the DSR functi - [Deploy the frontend app](../app-deployment/index.md) -- [3rd parties](../setup-3rd-party/index.md) +- [3rd parties](../../setup-3rd-party/index.md) -- [Configuration](../configuration/index.md) +- [Configuration](../../configuration/index.md) diff --git a/products/digital-sales-rooms/configuration/domain-config.md b/products/digital-sales-rooms/configuration/domain-config.md index 442e9754b..e2fb953f7 100644 --- a/products/digital-sales-rooms/configuration/domain-config.md +++ b/products/digital-sales-rooms/configuration/domain-config.md @@ -5,17 +5,31 @@ nav: --- +::: warning +Based on the business use case, the merchant can decide to add *Digital Sales Rooms* to their existing sales channel or new sales channel. +When you run the frontend app server (in both development or production), you will always have a specific domain (eg: `http://localhost:3000`) +::: + # Domain Configuration for frontend app -When you run the frontend app server (in both development or production), you will always have a specific domain (eg: `https://dsr-frontends.com`). This section will show you how to add this domain to sales channel. +This section will show you how to add these domains to sales channel. + +## Setup domains for Digital Sales Rooms + +::: warning +Please redeploy or rerun your frontend app to apply the domains changes into it. +::: + +- After specifying the sales channel, head to the *Domains section* and add appropriate *Digital Sales Rooms* domains with appropriate languages. *Digital Sales Rooms* can switch languages by the path, you can choose your domain path represents for a language. Here is our recommendation: -## Setup sales channel for Digital Sales Rooms -- Based on the business use case, the merchant can decide to add *Digital Sales Rooms* to their existing sales channel or new sales channel. -- After specifying the sales channel, head to the *Domains section* and add appropriate *Digital Sales Rooms* domains with appropriate languages. *Digital Sales Rooms* can switch languages by the path, so ensure to add the domains with the format below. ``` -dsr-frontends.com - English -dsr-frontends.com/de-DE - Deutsch +http://localhost:3000 - English +http://localhost:3000/de-DE - Deutsch +http://localhost:3000/en-US - English (US) ``` + ![ ](../../../assets/setup-domain-for-sales-channel-DSR.png) -The *Digital Sales Rooms* domain (eg: `https://dsr-frontends.com`) should be selected as *Default appointment domain* in [Configuration Page - Appointments](./plugin-config.md#appointments) +- These *Digital Sales Rooms* domains should be selected as *Available domains* in [Configuration Page - Appointments](./plugin-config.md#appointments) + +![ ](../../../assets/fill-domain-into-configuration.png) diff --git a/products/digital-sales-rooms/configuration/plugin-config.md b/products/digital-sales-rooms/configuration/plugin-config.md index 022b35f11..7c6d3e81d 100644 --- a/products/digital-sales-rooms/configuration/plugin-config.md +++ b/products/digital-sales-rooms/configuration/plugin-config.md @@ -19,7 +19,7 @@ Open Shopware CMS, select **Marketing** > **Digital Sales Rooms** > **Configurat ### Appointments -- *Default appointment domain* - This select box shows the list of domains of all sales channel. You should choose the *Digital Sales Rooms* domain from [this section](./domain-config.md) +- *Available domains* - This select box shows the list of domains of all sales channel. You should choose the *Digital Sales Rooms* domains from [this section](./domain-config.md) ### Video and Audio @@ -28,7 +28,7 @@ Open Shopware CMS, select **Marketing** > **Digital Sales Rooms** > **Configurat ### Realtime service -- *Hub url* - get the value from [this section](../setup-3rd-party/realtime-service-mercure.md#setup-via-stackhero-recommended) -- *Hub public url* - get the value from [this section](../setup-3rd-party/realtime-service-mercure.md#setup-via-stackhero-recommended) -- *Hub subscriber secret* - get the value from [this section](../setup-3rd-party/realtime-service-mercure.md#setup-via-stackhero-recommended) -- *Hub publisher secret* - get the value from [this section](../setup-3rd-party/realtime-service-mercure.md#setup-via-stackhero-recommended) +- *Hub url* - get the value from [this section](../setup-3rd-party/realtime-service-mercure.md#attach-mercure-information-into-digital-sales-rooms) +- *Hub public url* - get the value from [this section](../setup-3rd-party/realtime-service-mercure.md#attach-mercure-information-into-digital-sales-rooms) +- *Hub subscriber secret* - get the value from [this section](../setup-3rd-party/realtime-service-mercure.md#attach-mercure-information-into-digital-sales-rooms) +- *Hub publisher secret* - get the value from [this section](../setup-3rd-party/realtime-service-mercure.md#attach-mercure-information-into-digital-sales-rooms) diff --git a/products/digital-sales-rooms/index.md b/products/digital-sales-rooms/index.md index c81c22301..e5deb1a74 100644 --- a/products/digital-sales-rooms/index.md +++ b/products/digital-sales-rooms/index.md @@ -21,6 +21,8 @@ You can create interactive live video events for your customers straight from yo *Digital Sales Rooms* application does not belong to *the default Storefront*. It's a standalone Frontend app running with Nuxt instance. This template will be hosted in a separate instance with a new domain, which will be different from the Storefront domain. ::: +To use the Digital Sales Rooms plugin, you must perform **installation** & **3rd parties setup** & **plugin configuration**. + ## Prerequisites Review the below minimum operating requirements before you install the *Digital Sales Rooms* feature: @@ -33,4 +35,5 @@ Review the below minimum operating requirements before you install the *Digital * [Daily.co](https://daily.co/) - Refer to setup instructions for [realtime video call](./setup-3rd-party/realtime-video-dailyco.md) * [Mercure](https://mercure.rocks/)- Refer to setup instructions for [realtime Mercure service](./setup-3rd-party/realtime-service-mercure.md) + Following section guides you on the installation procedure. diff --git a/products/digital-sales-rooms/local-installation/admin-side-installation.md b/products/digital-sales-rooms/installation/admin-side-installation.md similarity index 92% rename from products/digital-sales-rooms/local-installation/admin-side-installation.md rename to products/digital-sales-rooms/installation/admin-side-installation.md index 2480563c3..f2a1661c2 100644 --- a/products/digital-sales-rooms/local-installation/admin-side-installation.md +++ b/products/digital-sales-rooms/installation/admin-side-installation.md @@ -13,7 +13,7 @@ Digital Sales Rooms plugin is a licensed plugin. If you already know how to inst ::: warning As part of the Shopware Beyond plan, the Digital Sales Rooms is available to you as an extension. -Same with other plugins, you have multiple ways to fetch the plugin via composer, direct download or through your Shopware Account. +Same with other plugins, you have multiple ways to install the plugin via composer, direct download or through your Shopware Account. ::: In this part, we will learn how to get and install the *Digital Sales Rooms* plugin into local Shopware instance. @@ -23,6 +23,7 @@ In this part, we will learn how to get and install the *Digital Sales Rooms* plu If you are a merchant with Shopware Beyond, you can access account.shopware.com and create a wildcard environment with attached plugins. Refer to [guideline](https://docs.shopware.com/en/account-en/extension-partner/wildcard-environments) for more info. ![ ](../../../assets/products-digitalSalesRooms-wildcard.png) + By this way, you can get the plugin quickly into Shopware instance via multiple ways (via composer, direct download or through your Shopware Account). ### Via download @@ -41,7 +42,7 @@ To install a plugin via composer, follow these steps: - From wildcard environment detail page, click on the plugin and then click on the "Install via composer" button. - A modal will appear and contain all command lines to install. -## Activate the plugin in Admin Extension +## Install & activate the plugin Once you fetched the plugin, you can run the below Symfony commands for activate plugin: diff --git a/products/digital-sales-rooms/installation/app-installation.md b/products/digital-sales-rooms/installation/app-installation.md new file mode 100644 index 000000000..b78a958e8 --- /dev/null +++ b/products/digital-sales-rooms/installation/app-installation.md @@ -0,0 +1,74 @@ +--- +nav: + title: Frontend app installation + position: 30 + +--- + +# Frontend App Installation + +::: warning +This template is built based on the Shopware Frontends framework, so it inherits from Shopware Frontends & Nuxt 3 concepts. +::: + +## Init environment + +- Install pnpm with global scope +``` +npm install -g pnpm +``` + +- From the Shopware root folder ``, go to the folder of *Digital Sales Rooms* templates. +``` +cd ./custom/plugins/SwagDigitalSalesRooms/templates/dsr-frontends +``` + +## Generate env file + +- Assume Shopware platform is running at `http://localhost:8000` & frontend app will run in `http://localhost:3000`. + +``` +cp .env.template .env +``` +**ORIGIN**: This is current frontend app domain. E.g: `http://localhost:3000` + +**SHOPWARE_STOREFRONT_URL**: This is default Shopware storefront domain. E.g: `http://localhost:8000` + +**SHOPWARE_ADMIN_API**: This is Shopware admin-api domain server. E.g: `http://localhost:8000/admin-api` + +**SHOPWARE_STORE_API**: This is the Shopware store-api domain server. E.g: `http://localhost:8000/store-api` + +**SHOPWARE_STORE_API_ACCESS_TOKEN**: This is the Shopware Access Token to connect to Shopware API. Head to sales channel you assign the *Digital Sales Rooms* domain, find the `API access` section, and copy the `API access key`. + +**ALLOW_ANONYMOUS_MERCURE**: This is the flag for development only. When the value = 1, it means your app is running with unsecured Mercure. + +## Run frontend App + +For development, you can run the dev server by the following commands: + +- Install dependencies +``` +pnpm install +``` + +- Run dev server +``` +pnpm dev +``` +Usually, port `3000` is the default port so that you can access the domain of the Frontend App `http://localhost:3000/` + +# Build frontend App + +For production, you can build code by the following commands: + +- Install dependencies +``` +pnpm install +``` + +- Build +``` +pnpm build +``` + +Following section guides you on 3rd parties setup procedure. \ No newline at end of file diff --git a/products/digital-sales-rooms/installation/index.md b/products/digital-sales-rooms/installation/index.md new file mode 100644 index 000000000..8b3f31ef8 --- /dev/null +++ b/products/digital-sales-rooms/installation/index.md @@ -0,0 +1,14 @@ +--- +nav: + title: Installation + position: 10 + +--- + +# Digital Sales Rooms Installation + +::: warning +This section will show how to install *Digital Sales Rooms* plugin into the existing Shopware platform. It will not introduce how to install Shopware platform. +::: + +This includes installation at admin and at template. Following sections gives you a detailed procedure of installation. diff --git a/products/digital-sales-rooms/local-installation/app-installation.md b/products/digital-sales-rooms/local-installation/app-installation.md deleted file mode 100644 index 94e55c159..000000000 --- a/products/digital-sales-rooms/local-installation/app-installation.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -nav: - title: Frontend app installation - position: 30 - ---- - -# Frontend App Installation - -::: warning -This template is built based on the Shopware Frontends framework, so it inherits from Shopware Frontends & Nuxt 3 concepts. -::: - -## Init environment - -- Install pnpm with global scope -``` -npm install -g pnpm -``` - -- From the Shopware root folder ``, go to the folder of *Digital Sales Rooms* templates. -``` -cd ./custom/plugins/SwagDigitalSalesRooms/templates/dsr-frontends -``` - - -## Generate env file -``` -cp .env.template .env -``` -**SHOPWARE_ENDPOINT**: This is the Shopware API Domain server. - -**SHOPWARE_ACCESS_TOKEN**: This is the Shopware Access Token to connect to Shopware API. Head to sales channel you assign the *Digital Sales Rooms* domain, find the `API access` section, and copy the `API access key`. - -**ALLOW_ANONYMOUS_MERCURE**: This is the flag for development only. When the value = 1, it means your app is running with unsecured Mercure. - - -## Run frontend App -- Install dependencies -``` -pnpm install -``` - -- Run dev server -``` -pnpm dev -``` -Usually, port `3000` is the default port so that you can access the domain of the Frontend App `http://localhost:3000/` diff --git a/products/digital-sales-rooms/local-installation/index.md b/products/digital-sales-rooms/local-installation/index.md deleted file mode 100644 index 1602f591c..000000000 --- a/products/digital-sales-rooms/local-installation/index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -nav: - title: Local Installation - position: 10 - ---- - -# Digital Sales Rooms Installation - -::: warning -This section is for local installation only. -::: - -This section will show how to install *Digital Sales Rooms* plugin into your local machine. - -This includes installation at admin and at template end. Following sections gives you a detailed procedure of installation. diff --git a/products/digital-sales-rooms/setup-3rd-party/realtime-service-mercure.md b/products/digital-sales-rooms/setup-3rd-party/realtime-service-mercure.md index 138e1fef1..cd991aa36 100644 --- a/products/digital-sales-rooms/setup-3rd-party/realtime-service-mercure.md +++ b/products/digital-sales-rooms/setup-3rd-party/realtime-service-mercure.md @@ -12,23 +12,11 @@ Symfony provides a straightforward component, built on top of the [Mercure](http [Mercure](https://mercure.rocks/docs/getting-started) is an open protocol designed from the ground up to publish updates from server to client. It is a modern and efficient alternative to timer-based polling and to WebSocket. ::: -## Mercure general settings -Detailed below is the minimum configuration needed for a working stack apart from project-specific CMS configurations. -- *Set up CORS allowed origins* - In our case, it would be the domain where the Shopware Frontends is hosted and available. For instance: https://dsr-frontends.com (frontend). -- *Set up publish allowed origins* - The domains that request the Mercure service must be added to publish allowed origins or else it gets rejected. For instance (HTTP protocol must not be included): shopware-pwa-gs.herokuapp.com (frontend) and pwa-demo-api.shopware.com(backend - API). -- *Set up the publisher (JWT) key* - Set whatever you want. -- *Set up the subscriber (JWT) key* - Set whatever you want. - -There are 4 main pieces of information from Mercure Hub you have to get: -- *Hub url* - The hub URL. -- *Hub public url* - The hub public URL, normally it's the same as the hub URL. -- *Hub subscriber secret* - The JWT key used for authenticating subscribers -- *Hub publisher secret* - The JWT key used for authenticating publishers - -## Setup +## Setup hub There are different ways to set up Mercure as listed below: ### Setup via Stackhero (Recommended) + ::: info 💡 We tested the service provided by [StackHero](https://www.stackhero.io/en/services/Mercure-Hub/pricing). Depending on the expected traffic, you can easily switch between the plans. For a small demo among a few people at the same time, the “Hobby” plan is sufficient. ::: @@ -37,7 +25,7 @@ There are different ways to set up Mercure as listed below: - Access the dashboard. - In the **Stacks** menu item, create a new stack with the **Mercure Hub** service. - When creating a stack successfully, tap into the Configure button. -- On this page, it's easy to find the [Mercure general settings](#mercure-general-settings), copy all the necessary information, and paste it into [the proper inputs of the configuration page](../configuration/plugin-config.md#realtime-service). +- On this page, it's easy to find the [Mercure general settings](#attach-mercure-information-into-digital-sales-rooms), copy all the necessary information, and paste it into [the proper inputs of the configuration page](../configuration/plugin-config.md#realtime-service). ![Mercure configuration](../../../assets/products-digitalSalesRooms-mercureConfig.png) @@ -107,3 +95,21 @@ ui 0 ... } ``` + +## Config Mercure hub + +After init mercure hub, let's make it more secure with your information: +- *Set up CORS allowed origins* - In our case, it would be the domain where the Shopware Frontends is hosted and available. For instance: `http://localhost:3000` (frontend domain). +- *Set up publish allowed origins* - The domains that request the Mercure service must be added to publish allowed origins or else it gets rejected. For instance (HTTP protocol must not be included): `http://localhost:3000` (frontend domain) and `http://localhost:8000` (backend API domain). +- *Set up the publisher (JWT) key* - Set whatever you want. +- *Set up the subscriber (JWT) key* - Set whatever you want. + +## Attach Mercure information into Digital Sales Rooms + +From your Mercure hub, it's easy to get the proper information: +- *Hub url* - The hub URL. +- *Hub public url* - The hub public URL, normally it's the same as the hub URL. +- *Hub subscriber secret* - The JWT key used for authenticating subscribers +- *Hub publisher secret* - The JWT key used for authenticating publishers + +Then, fill them in [Configuration Page - Realtime service](../configuration/plugin-config.md#realtime-service)