Web Registration Wizard

WebRTC application supports showing the Web Registration Wizard as the initial screen of the app. The Wizard can be used to collect the initial parameters required for provisioning the application by showing a pre-configured web URL.

While the design and content of the page shown at the URL are completely up to you, WebRTC app needs a couple of things to be able to integrate with the web page shown.

Note

You can make use of Client API parameters to differentiate the page shown at Web Registration Wizard URL if you’re also using the same for mobile apps. For example, you can make use of the %platform% parameter in your URL which would resolve to iOS, Android or Chrome (in case of WebRTC).

Embed Script

WebRTC app requires a script to be embedded into all the pages being shown in the initial screen. The script can easily be embedded by including a <script> tag to your page with it’s source URL set to <your-webrtc-domain>/assets/web-registration.js and id webrtc-webreg-intercept. For example — if your app is hosted on your-webrtc-app.com, the embed script can be included by adding:

<script src="https://your-webrtc-app.com/assets/web-registration.js" id="webrtc-webreg-intercept"></script>

When you’re testing the editable version of the app, you don’t need to add testing=1&reprovision=1 parameters at the end of the url, so your link to the script will look like this:

<script src="https://your-webrtc-app.testing.cloudsoftphone.com/assets/web-registration.js" id="webrtc-webreg-intercept"></script>

The embed script adds a top level WebRTCApp object to the page which you can access via your JavaScript code. The object has the following members defined:

WebRTCApp Object
Member Type Description
signin(uri) function A function that takes your provisioning scheme URI (csc: by default) and passes it to the WebRTC app
cid string Cloud ID of the application
provisioningScheme string Provisioning scheme for your application configured in CSP

Once the script is added, you should listen for the WebRTCAppReady event on the global window object to be notified once WebRTC is ready to receive your requests. For more details, look at the 2. Using JavaScript example below.

Passing Provisioning URI to WebRTC

With the above script embedded into the page, you have two different options for passing the required username and password parameters to the WebRTC app. Both methods require that you construct a URI following the provisioningScheme:username:password@CloudID format. Username and Password parameters in the URI need to be properly URI-encoded so any special characters can properly be handled. You can read detailed instructions on how to properly format and construct the provisioning URI in Initial Screens documentation.

Note

While CloudID is part of the format, it isn’t used by WebRTC, since Cloud ID of white label apps is already hardcoded, and cannot be changed.

Note

WebRTC now supports appending the * character at the end of the username or CloudID to enable Testing configuration via the provisioning URI. For more information on how to enable Testing Mode in WebRTC, please refer to the Testing Mode documentation.

The URI can be passed to the WebRTC application using one of the following ways:

1. Using <a> tag

Once you have a correctly formatted URI ready, you can create and show an <a> tag on your page with it’s href attribute set to the URI. The embedded script will automatically intercept any links which have URIs defined with your configured provisioning scheme. For example, your page can show the a link like:

<a href="csc:john_smith:my_password@CODE">Start App</a>

As the user click’s the above link, WebRTC app will take over and if the supplied username and password are correct, the user will be provisioned and logged in to the application.

2. Using JavaScript

Fully formatted provisioning URI can be passed to the WebRTC app using JavaScript as well. Once you embed the web-registration.js script into your page, you should listen for the WebRTCAppReady event on the window object. The event is dispatched when the WebRTC app is ready to accept your requests. Once the event is fired, you have access to a global WebRTCApp object. This object exposes a signin(uri) method which takes a single string URI as a parameter. You also have the provisioningScheme and cid parameters available on the WebRTCApp object.

// somewhere on your page
window.addEventListener('WebRTCAppReady', () => {

    const username = 'john_smith';
    const password = 'my_password';
    const { provisioningScheme, cid } = WebRTCApp;
    const uri = provisioningScheme + ':' + username + ':' + password + '@' + cid;

    // you can also use window.WebRTCApp.signin(uri)
    WebRTCApp.signin(uri);
});

Calling this method with your formatted URI will trigger the provisioning process and the user will be signed into the application.

Warning

Trying to access the global WebRTCApp object before the WebRTCAppReady event is dispatched will cause errors in your workflow, since the object is not available until the event is fired.

Handling Errors

In case WebRTC application encouters an error while trying to provision the app and sign the user in, it will display an error notification to the user and then reload the original configured Web Registration Wizard URL in the <iframe> with an error parameter appended as a query string. You can then read the error parameter to determine what went wrong with the provisioning and authentication process and guide the user accordingly.