Build a Site Plugin in Blocks

A site plugin is a type of component that site builders can place in designated locations (called slots) within Wix apps. Site plugins extend the functionality of their host by providing additional Ul elements and business logic.

To build a site plugin, you need to do the following:

• In Wix Blocks, design your site plugin's UI and code its business logic.
• In the app dashboard in Wix Studio, set up your app's extensions, authentication, permissions, and more.

You can create a new app for your site plugin or add it to an existing app.

Step 1 | Design your site plugin in Wix Blocks

1. Open an existing Blocks app or create a new app.
2. Open the Widgets and Design panel, click , and select Add Plugin.
3. の中で Add a plugin panel, do the following:
   • Enter your plugin's name. This is the name that will be shown to users in the editor.
   • Select the Wix app the your plugin extends. The selected app is automatically added as a dependency.
   • Select the slots to which your plugin can be added. Learn more about available slots for each app.

   Note: You can change these settings at any time in the plugin's extension page in the app dashboard.

4. 作成」をクリックする。
5. クリック エレメントの追加 to open the エレメント panel.
6. Drag and drop the elements you need, and adjust their layout and design.

Make sure to follow our design guidelines.

Step 2 | Code your plugin

A plugin communicates with its host widget via an API that the plugin is expected to expose. The host widget uses this API to provide the plugin with data about the context in which it’s running (for example, a reviews plugin exposes a productId property, which the host widget sets to indicate the item that it’s currently displaying).

Depending on your implementation, your plugin may also need to communicate with external servers.

Connect the plugin's API

To implement the plugin API, you first need to add the required properties and functions to your Blocks Widget API. Learn more about the plugin APIs supported on each app page.

You can then get the properties provided by the host widget in your plugin's onPropsChanged() function, for example:

1

Develop the plugin code

Use Wix Blocks to code your plugin’s business logic. Plugins can use Wix App APIs to access the site’s business data (such as Stores or Bookings data).

Step 3 | Configure your plugin’s editing experience

In the Blocks Configuration tab you determine how site builders will interact with your plugin when they add it to their site using any of the Wix editors. You have full control over what users will be able to change in the widget’s design and layout and how it behaves in editing time. You can also build an integrated settings panel, enabling site builders to customize the plugin.

Step 4 | Build your app's dashboard page

If your plugin requires a back office management interface, you can create one either within the Wix dashboard, or as an external dashboard on a third-party platform. Learn about building a dashboard page extension

Add your plugin to a slot from a dashboard page

To let users add your plugin to their site through your app's dashboard page, create a user interface that triggers the Wix Dashboard API's addSitePlugin() function. Specify the desired slot when calling this function. This initiates a user flow where Wix requests the user's consent to add the plugin. If the selected slot is already occupied, the user can choose to replace the existing plugin with your plugin. Plugins for the checkout page must implement this functionality to enable users to add the plugin to their site.

Depending on the framework you're using to develop your dashboard page, use one of the following APIs:

• Velo in Blocks: addSitePlugin().
• Wix SDK: addSitePlugin().

について addSitePlugin() function takes the following parameters:

• pluginId: ID of your site plugin, which you can find in your app's site plugin extension. To view the extension, go to your app's dashboard in the Wix Studio workspace.
• placement: Details of the slot in which you want to add the plugin, including the hosting app's appDefinitionId, and the relevant widgetId そして slotId. Learn more about the locations and identifiers of slots that are available on Wix app pages.

The following example shows how to use Velo in Blocks to add a site plugin to the checkout page when a user clicks an Add Plugin button in the dashboard:

1

Check your plugin's placement status

You can check whether your plugin is currently placed in a slot on a specific site. Depending on the framework you're using to develop your dashboard page, use one of the following APIs:

• REST: Get Placement Status
• Velo in Blocks: getPlacementStatus()

Both APIs return an array of objects indicating whether each of your app's site plugins is currently placed in a slot on the user's site.

例えば、こうだ：

1

Step 5 | Configure your plugin's settings in your app dashboard

You can configure various settings, including the plugin's installation settings and market listing, in your app's site plugin extension page in the app dashboard. You can navigate to this page directly from the Blocks editor.

Your plugin's market listing determines how it will appear to users in the plugin explorer in the editors, including the plugin's name, icon, and teaser.

1. の中で Widgets and Design panel in the left sidebar, hover over your plugin's name and click the もっと見る icon, and then click Plugin Settings.
   The app dashboard opens in a new tab, showing your app's site plugin extension page.
2. Configure the following:

   • Plugin name: The plugin name that is displayed to users.

   • Which Wix app does it extend?: The Wix app for which you're building the plugin.

   • Slots this plugin can be added to: Select one or more slots that are appropriate for your plugin. Select slots in order of priority. If none of the selected slots are available, users can choose to replace a plugin that’s already been added.

   • Add this plugin automatically to the site: Whether the plugin is automatically added to a slot when a user installs your app.

     Checkout plugins
     Note that plugins for the checkout page cannot be added automatically on installation.

   • Teaser: A short promotional description for your plugin's market listing.

   • Icon: An icon for your plugin's market listing. Upload a square JPG or PNG file.

   Note: If you set your plugin to be automatically added to a slot on installation, it will be placed in the first available slot according to the order you defined. If that slot is occupied, it will be added in the next available slot, and so on. If there are no available slots, it will not be added.

3. To apply changes made in the app dashboard, go back to the Blocks editor and build the app again to create a new version.
4. If your app is already approved and published, publish a new version in the app dashboard.

Step 6 | Test and preview

Your unpublished plugins are available for installation in the editors when you're logged in with your developer account. This makes it easy to preview and test your plugin in a real environment.

To test your plugin in the editor:

1. Create a site and install the Wix app that your plugin extends.
2. Go to the page on which you want to install your plugin, and click the host widget's Plugin icon.
   Your unpublished plugins will appear in the plugin explorer.
3. Hover over your plugin, and then click Add.
   When prompted for consent, select the checkbox and click Agree & Add.

Once you install your plugin on a site, you can preview or publish the site to test the plugin's functionality and make sure it's working properly.

Test a plugin for the checkout page

If you're developing a plugin for the checkout page, make sure you've set up a way to install your plugin from the dashboard and then do the following:

1. Create a Premium development site. Select Wix Stores as the business solution.
2. サイトを公開する。
3. In your app's dashboard, from the Test Your App menu, install your app on the development site.
4. Go to the site's dashboard, navigate to your app's dashboard page, and add the plugin to the checkout page.
5. Preview the checkout process on your development site.

Step 7 | Submit and publish your plugin

When you’ve finished building and testing your plugin, you’re ready to launch and monetize your app.

Learn more about submitting your app for review.

See also

• Tutorial | Create an App in Wix Blocks
• Tutorial | Create a Site Plugin for the Wix Stores Product Page
• Tutorial | Create a Site Plugin for the Wix Bookings Service Page