Tutorial | Set Up an App with the App Dashboard

This tutorial shows you how to set up a new Wix app using the app dashboard. The tutorial shows you how to create, configure, and test an externally hosted "Product of the Day" app that can be installed on a Wix site. The app lets site admins offer a daily discount on a product they choose.

Upon downloading the app, the site gains access to the following features:

• In the site dashboard: A dashboard page where a site admin can choose a product from their catalog to discount.
• In the site: An automated chat message offering site visitors a discount coupon for the selected product.

The dashboard page extension is built with React and the server with Express.js. We provide all the code you need for this app in the example apps GitHub repository. Regardless of the technologies you use to build your app, you can take similar steps to integrate it with the app dashboard.

The end result will look like this:

We'll take the following steps to implement the Product of the Day app:

1. Clone the app repository.
2. Create an app from the Custom Apps page in your Wix Studio workspace.
3. Configure permissions for your app.
4. Set up the dashboard page extension.
5. Set up the app's backend.
6. Test the app out locally.

Before you begin

Before getting started, make sure that:

• You have Node.js (v16.4 or higher).
• You're logged into your Wix Studio account. If you don't already have one, sign up for a Wix Studio account.

Step 1 | Clone the app repository

This tutorial uses a pre-built app we've saved in the example apps GitHub repository.

To clone the repository to your computer, open the terminal and run the following command from the folder you want to clone the repository into:

Then navigate to the folder containing the Product of the Day app:

Within this folder you can find both the backend app server (in the server folder) and the frontend dashboard component (in the client folder).

Step 2 | Create an app in the Custom Apps page of your Wix Studio workspace

The Custom Apps page in your Wix Studio workspace is the place for managing Wix apps you develop. Follow these steps to create a Wix app that we'll connect to the external servers.

1. Go to Wix Studio and sign in.

2. If this is your first Wix app, click Start Building. If you already have an app, click Create New App in the top-right corner. This opens your new app's dashboard:

   

3. Click the default name generated for your app, and enter a new one, such as "Product of the Day".

Step 3 | Configure permissions for your app

This app uses Wix REST APIs to access and manage Wix site data, requiring specific permissions to access each endpoint. To ensure functionality, your app needs these permissions from any site using it. This section guides you through setting up your app to request these permissions upon installation.

Find required permissions

To find the permissions that your app requires:

1. Go to the Wix REST API reference documentation.

2. Find the specific endpoints that your app calls. The Product of the Day app calls the following endpoints:

   • Query Products: To retrieve information about products in the site's catalog.
   • Create a Coupon: To generate a discount coupon for the product the site owner chooses.
   • Send Message: To send site visitors a message with the coupon in the Wix Chat widget.

3. In each endpoint reference, look for Permission Scopes:

   

   The Product of the Day app requires the following permission scopes:

   Endpoint	Required permissions
   Query Products	Read Products
   Create a Coupon	Manage Coupons (with the identifier SCOPE.DC-COUPONS.MANAGE-COUPONS)
   Send Message	Manage Inbox Messages

Add permissions

To add permissions for the app to request upon installation:

1. Go to Permissions in your app's dashboard.
2. For each permission scope:
   1. In the left sidebar, click Add Permissions.
   2. Enter the permission scope's name in the Search by name or ID field.
   3. Check the permission scope's checkbox under Choose Permission Scopes.
   4. Click Save.

Now, when a site owner installs the app, Wix prompts them to grant the necessary permissions.

Step 4 | Set up the dashboard page

Every Wix site has a dashboard where site admins manage their site and business. Our app integrates with this dashboard by adding a new page where site admins can select a product of the day and apply discounts. The dashboard page is built with React. This section guides you through adding the dashboard page to your app.

Run a local server

Our app includes two servers: one for the dashboard page UI (in the client folder) and one for the app's backend business logic (in the server folder).

To run the local development server for the dashboard page UI:

1. Navigate to the client folder:

   Copy

2. Install the dependencies:

   Copy

3. Start the local server for the dashboard page:

   Copy

   This runs the local dashboard page server and opens your browser to https://localhost:3000.

   Note: If you encounter a security warning, click Advanced and then Proceed to localhost (unsafe).

Now, you can see the dashboard component open in your browser:

Add a dashboard page

To set up your app to include the dashboard page:

1. In the left sidebar, click Extensions.

2. Click Create Extension.

3. Check the Dashboard checkbox.

4. In the Dashboard Page card, click Create.

   

5. Under Page info, in the iFrame URL field, enter the address for your local dashboard page server: https://localhost:3000/.

   

6. Under Sidebar configuration, in the Page name field, enter a name for your dashboard page. This name is shown in the dashboard sidebar menu.

   

7. Click Save.

Your app is set to add a dashboard page upon installation on a site and load it from the specified URL.

Step 5 | Set up the backend

Our app contains business logic in our backend server. This section guides you through setting up the backend, including authentication for your app.

Configure environment variables

To configure environment variables for authentication:

1. In the product-of-the-day/server folder, create a file named .env with the following placeholder values:

   Copy

   Note: Only the webhook public key value needs to be enclosed in quotes.

2. In the left sidebar, click OAuth.

3. In the .env file created in the first step, replace <APP_ID> with the App ID and <APP_SECRET KEY> with the App Secret Key.

   

Add a webhook to your app

Webhooks deliver real-time notifications about events in your app, other apps, or the Wix site. For this app, we'll add the Message Sent To Business webhook, which notifies the app whenever a site visitor sends a message in the Wix Chat widget.

To add a webhook:

1. In the left sidebar, click Webhooks.

2. Click Add Webhook.

3. Under API Category, select Inbox.

4. Check the box next to Message Sent To Business.

5. In the Callback URL field, enter a temporary dummy URL, such as https://www.test.not. We'll replace this URL after activating the backend app server.

6. Click Save. This takes you back to the Webhooks page.

7. Under Public key, click Open.

8. Click Copy Key.

9. In your .env file, replace <APP_WEBHOOK_PUBLIC_KEY> with the key value:

   Copy

Start the backend server

To successfully set up our app, the server for the dashboard page and the backend server need to be running at the same time. To start the backend server:

1. Open a new terminal window, and navigate to product-of-the-day/server:

   Copy

2. Install the app's dependencies:

   Copy

3. Start the local app server:

   Copy

   This runs the local app server and displays several important URLs:

   

   • RedirectUrl: Endpoint Wix must redirect to after the user authenticates.
   • AppUrl: Main entry point for the app's backend functionality.
   • Message received webhook: Used for receiving callbacks from Wix.

4. Copy the RedirectUrl, AppUrl, and Message received webhook and keep them available for the next steps.

Configure OAuth

Wix uses OAuth 2.0 to authorize apps to access our APIs and receive webhooks. To configure OAuth:

1. In the left sidebar, click OAuth.
2. Under URLs:
   • Enter the AppUrl from the previous step into the App URL field.
   • Enter the RedirectUrl from the previous step into the Redirect URL field.
3. Click Save.

Configure the webhook

To make sure your app receives the webhook:

1. In the left sidebar, click Webhooks.
2. In the Webhook List, next to the Message Sent to Business webhook, click the ellipsis . Then, click Edit.
3. In the Callback URL field, enter the Message received webhook URL from the previous step.
4. Click Save.

Your app is now properly configured and ready to test.

Step 6 | Test the app

Wix provides a free Premium development site so you can easily install your app and see it working. In this step, you'll create a development site, install your app on the site, and try it out.

Set up a development site

To set up a development site:

1. In your app's dashboard, click Test Your App in the top right and then click Create Development Site.

2. In the list of business solutions to install on the development site, click Wix Stores, then click Create Site.

   

3. Go to Wix.com.

4. In your Sites page, find the development site you just created. The automatically generated name begins with Dev Site.

5. Hover over the development site and click Select & Edit Site. This opens the site's dashboard.

6. Click Design Site. This opens the site's editor.

7. Add a product page to the site:

   1. In the left sidebar, click Pages & Menu .
   2. In the Stores Pages tab, select Product Page.
   3. Click Add Shop Page.

8. Back in the editor, on the top right, click Publish.

Your development site is now live.

Install the app

To install the app on your development site:

1. Return to your app's dashboard.
2. Click Test Your App, then click App Market Website. This takes you to a page for your app in the Wix App Market.
3. Click Add to Site.
4. Next to the development site you just created, click Select.
5. Wix now requests the site permissions your app requires. Click Agree & Add.

The Product of the Day app is now installed on your development site.

Try out the dashboard page

To test the app, we'll start by trying out its dashboard page, where we can choose a product of the day and apply a discount:

1. Open the development site's dashboard. Your app now appears in the left dashboard sidebar under the name you entered earlier. Click your app's name in the sidebar.

   

   This opens your app's dashboard page.

2. Click Choose Product.

   

   This opens a menu to select a product.

3. Your development site's catalog is filled with example products with the name "I'm a product". To make these products appear, type "I'm" in the Search by product name field. Then, select a product and click Done.

   

4. Adjust the percentage Discount to apply to the product, and click Update.

   

You've now selected a product of the day and applied a discount to it.

Try out the site

Now let's see what the experience is like for a site visitor.

1. Open your development site's editor, hover over Publish in the top right, then click View Site to open your live site.

2. In your live site, click the chat icon on the bottom right to open the chat widget.

3. In the chat widget, type any text. For example, "Hello".

4. After a few moments, you'll receive a response in the chat widget, offering you a discount on the product of the day:

   

5. The chat response contains a coupon code and a link. Copy the coupon code, and click the link to go to the product page for the product of the day.

6. In the product page, click Add to Cart. Then, to go to the cart page, click View Cart.

7. Click Enter a promo code, paste the coupon code you copied, and click Apply.

   

Your Order Summary now incorporates the Product of the Day discount:

Step 7 | Customize the app

The Product of the Day app is now working!

To learn more about how the app works, take a look around the code files in the GitHub repo.

As an exercise to help familiarize yourself with app code a little more, you can add additional functionality to this app.

For example, edit the code so that each site visitor can only receive one discount coupon per day. To do this, edit product-of-the-day/server/src/services/ProductOfTheDayService.js, and add the lines of code marked as ADDED below in the comments:

With this adjustment, the app now checks whether a discount coupon was already created for the site visitor on the current date. It only sends a coupon if one wasn't already sent.

What next?

Now that you've learned how to set up a pre-made, externally hosted Wix app, you can start thinking about building your own apps. Here are a few resources to get you started:

• Browse the Wix App Market to get inspiration from other apps.
• Learn about self-hosting for Wix apps.
• Get to know our REST API and our JavaScript SDK.
• Read our guidelines for submitting an app to the Wix App Market.