Creating an Installation Wizard

Introduction¶

Before users can use any Speakap Application, the application has to be installed by the network administrator through the Speakap Market (currently in limited beta). If desired, this installation process can be completed without any interaction with the application that is going to be installed, but applications can optionally provide an installation wizard which has to be completed before the installation is completed. This installation wizard is implemented and hosted by the creator of the application and is the perfect place for third parties to connect their backend with the Speakap platform.

Manifest entry¶

In order to create an installation wizard, an entry needs to be added to the manifest.json. The entry for the installation wizard would look something like this:

{
    "position": "install-wizard",
    "devices": "all",
    "url": "https://example.app.speakap.io/install"
}

Once this entry is present, the administrator installing the application will be presented with the wizard before he or she can complete the installation.

Wizard implementation¶

The actual wizard is implemented the same way as any other entry for the app, but in order to complete the wizard it needs to listen to a special saveSettings event through the Speakap Frontend Library, like so:

Speakap.on("saveSettings", function(event) {
    // perform some validation whether the user has successfully completed all
    // steps of the wizard
    if (everythingIsSuccessful) {
        Speakap.replyEvent(event, { status: "success" });
    } else {
        Speakap.replyEvent(event, { status: "failure" });
        Speakap.showError("An informative message explaining what went wrong");
    }
});

This saveSettings event is emitted whenever the user clicks the wizard’s “Install” button (the button is provided by the Speakap frontend, not the application) and once Speakap has received the “success” reply, it will consider the installation to be successful and the application will be made available to the network.

Please note the replies to the event may be generated asynchronously, so you still have an opportunity to make requests to your own application’s backend, for example.