# Using a Plug-In

# Adding a Plug-In

Before using a plug-in, you need to add the plug-in by clicking Settings > Third-Party Service > Plug-In Management in the Mini Program Admin Console. Developers can log in to the Mini Program Admin Console, and search for and add the plug-in by the appid. If no approval is required, the plug-in can be used directly. If approval is required, you need to get approved by the plug-in developer before using it in the Mini Program.

# Importing a Plug-In Code Package

Before using a plug-in, users need to declare the plug-in via app.json, for example:

Code example:

{
  "plugins": {
    "myPlugin": {
      "version": "1.0.0",
      "provider": "wxidxxxxxxxxxxxxxxxx"
    }
  }
}

As shown above, the definition field plugins can contain multiple plug-in declarations. Each plug-in declaration is identified by a plug-in reference name defined by a user, and specifies the appid of the plug-in and a required version number. The reference name (for example, myPlugin in the above example) is defined by the user, without being negotiated with the plug-in developer. The reference name is subsequently used to indicate the plug-in.

# Importing a Plug-In Code Package into a Subpackage

If a plug-in is used only within a subpackage, the plug-in can be placed only in the subpackage, for example:

{
  "subpackages": [
    {
      "root": "packageA",
      "pages": [
        "pages/cat",
        "pages/dog"
      ],
      "plugins": {
        "myPlugin": {
          "version": "1.0.0",
          "provider": "wxidxxxxxxxxxxxxxxxx"
        }
      }
    }
  ]
}

A plug-in within a subpackage is subject to the following service restrictions:

• The plug-in can be used only within the subpackage;
• A same plug-in cannot be simultaneously referenced by multiple subpackages;
• When the base library version is earlier than 2.6.0, a page outside the subpackage cannot be directly redirected to a plug-in page in the subpackage, but needs to be first redirected to a non-plug-in page in the subpackage and then to a plug-in page in the subpackage.

# Using a Plug-In

The plug-in code is invisible to a user of the plug-in. To use the plug-in correctly, the user should view the Development Documentation section on the plug-in details page and read the plug-in development document provided by the plug-in developer, to understand custom components, page names, and JS API specifications provided by the plug-in.

# Custom Component

The custom component provided by a plug-in is used in a same way as Using a Common Custom Component. To define a to-be-imported custom component via the json file, use the plugin:// protocol to indicate the reference name of the plug-in and the name of the custom component, for example:

Code example:

{
  "usingComponents": {
    "hello-component": "plugin://myPlugin/hello-component"
  }
}

To protect a plug-in, custom components provided by a plug-in are subject to some service restrictions:

• By default, instance objects of custom components of a plug-in cannot be obtained via the this.selectComponent API of the page.
• The >>> selector of APIs such as wx.createSelectorQuery cannot access the plug-in.

# Pages

Plug-in pages are supported as of the Mini Program base library 2.1.0.

To redirect to a plug-in page, prefix the value of url with plugin://, with a format of plugin://PLUGIN_NAME/PLUGIN_PAGE, for example:

Code example:

<navigator url="plugin://myPlugin/hello-page">
  Go to pages/hello-page!
</navigator>

# JS APIs

To call JS APIs of a plug-in, you can use the requirePlugin method. For example, if a plug-in provides a hello method and a variable world, the JS API can be called as follows:

var myPluginInterface = requirePlugin('myPlugin');

myPluginInterface.hello();
var myWorld = myPluginInterface.world;