# Initial Screens Cloud Softphone initial provisioning process requires the user to provide [Input Parameters for Provisioning](input_params.md) to complete successfully. Multiple types of initial screens are available to collect the input parameters. The types of initial screens are described below. ## Classic Initial Screen This is the default initial screen used by both the generic Cloud Softphone app and white-label apps. The screen consists of two input fields, a submit button, and a button which launches the QR code reader. The way how the user input gets processed depends on the type of the app, generic or whitelabel. ### Generic App The first of the input fields is titled "Cloud ID", the other one "Password". The text from first input field is processed by finding the **last** '@' character from the end of the string and splitting the string in two from this position. The first part is treated as **username**, the second part as **cloud ID**. The contents of the "Password" field is taken as **password**. !!! warning The value of username is url-decoded before use. **Examples:** | **input** | **username** | **cloud ID** | **note** | |---|---|---|---| | `CODE` | *(empty)* | CODE | empty username | | `user@CODE` | user | CODE | | | `user@CODE*` | user | CODE* | specifies test version of the app | | `someone@server.com@CODE` | someone@server.com | CODE | accepted | | `someone%40server.com@CODE` | someone@server.com | CODE | accepted, will be url-decoded to `someone@server.com@CODE` before use | ### White Label App Classic initial screen behaves slightly different in white label case. For white label apps, the cloud ID of the app is known and is hard-coded into the app binary during the white label build process. It is also possible to customize the initial screen, like change the textation, colors and it is also possible to hide the input fields and keep only the QR code reader, or hide the QR code part and keep just the input fields. Since the cloud ID is hard-coded and known, the content of the first input field is treated differently. Let's assume the cloud ID of our app is WLAPP. See the table below for examples: **Examples:** | **input** | **username** | **cloud ID** | **note** | |---|---|---|---| | `user` | user | WLAPP | hard-coded cloud ID is used | | `user@WLAPP` | user | WLAPP | the part after @ matches hard-coded cloud ID | | `user@WLAPP*` | user | WLAPP* | specifies test version of the app | | `user@OTHER*` | user | WLAPP* | different cloud ID is ignored, but * for test version is used | | `someone@server.com@WLAPP` | someone@server.com | WLAPP | accepted | | `someone%40server.com@WLAPP` | someone@server.com | WLAPP | accepted, will be url-decoded to `someone@server.com@WLAPP` before use | The main difference between the generic app case is that since cloud ID is known, single word is treated as username instead of cloud ID. When cloud id is explicitly entered, it is ignored and the hard-coded one is always used instead. In case the explicitly entered cloud id is appended by `*`, this `*` will be used to provision editable settings from the portal. ### Live vs. Editable Provisioning the editable version from classic initial screen is done by appending `*` character to **cloud ID** input parameter. For generic app, **cloud ID** needs to be always explicitly provided, so it's all about appending `*`. For white label apps, the **cloud ID** is embedded inside the app binary and it is normally not needed to enter it explicitly. It is embedded without the `*` character though, so to provision Editable version, the full form `user@CODE*` has to be entered into the first input field. ### QR Code The mobile applications have an embedded QR code reader which can be used to scan a code containing the login input parameters, making the login process easier. The code should contain text in the following format: `csc:username:password@CODE` `csc` : URI scheme prefix - required as-is `username` : this part will be url-decoded and used as **username** parameter `password` : this part will be url-decoded and used as **password** parameter `CODE` : this part will be used as **cloud ID** parameter !!! warning The **username** and **password** segments of the QR code contents should be url-encoded. Valid Cloud IDs contain only letters and digits, so url-encoding should have no effect on it. **Examples:** | **input** | **username** | **password** | **cloud ID** | |---|---|---|---| | `csc:CODE` | *(empty)* | *(empty)* | CODE | | `csc:user:12345@CODE` | user | 12345 | CODE | | `csc:someone%40server.com:%40%41%42@CODE` | someone@server.com | @AB | CODE | ## Provisioning link Provisioning link can be sent in a welcome email, via SMS or it can be shown in a web page. Clicking on such link in browser on a device which has the app installed will behave exactly the same as if the link was scanned by the embedded QR code scanner. The format of the link is similar to the QR code content described above: `csc:username:password@CODE` `csc` : URI scheme prefix - required as-is `username` : this part will be url-decoded and used as **username** parameter `password` : this part will be url-decoded and used as **password** parameter `CODE` : this part will be used as **cloud ID** parameter **Examples:** | **input** | **username** | **password** | **cloud ID** | |---|---|---|---| | `csc:username:@CODE` | user | *(empty)* | CODE | | `csc:user:12345@CODE` | user | 12345 | CODE | | `csc:someone%40server.com:%40%41%42@CODE` | someone@server.com | @AB | CODE | !!! warning The **username** and **password** segments of the provisioning link contents should be url-encoded. Valid Cloud IDs contain only letters and digits, so url-encoding should have no effect on it. !!! warning Since these links are handled by mobile browsers, they need to follow the strict URI formatting - the simplified form with username, but without password (like `csc:user@CODE`) will NOT work. You can specify empty password as `csc:username:@CODE` though. ## Registration Wizard Registration Wizard is only available in Cloud Softphone White Label apps. In case of white label apps, the **cloud ID** input parameter is embedded into the app binary and we only need to get the **username** and **password** from the user. Registration wizard is typically used to verify the user's phone number. It consists of two pages: ### Wizard Step 1 On this page, the user is asked to fill in his phone number, including country code. When done, the user clicks "Next" button. The app then uses [Phone Number Verifier](phone_number_verifier.md) web service to send user input to your server. The web service is supposed to send an activation code to the phone number the user has entered. When the web service response is successful, the registration wizard switches to Page 2 ### Wizard Step 2 On the second page, the user is expected to enter the activation or PIN code sent to him in Step 1. For Android devices it is possible to fill in the PIN code automatically from the incoming SMS if the SMS is in [proper format](android_sms_format.md). ### Wizard Completion When Step 2 is submitted, the app uses the hard-coded cloud ID as **cloud ID** input parameter, contents of the text field in Wizard Step 1 as **username** and contents of the text field in Wizard Step 2 as **password**. !!! note White Label apps which use Registration Wizard initial screen typically support External Provisioning web service, which receives the **username** and **password** input parameters and verifies that the PIN code matches the one generated by [Phone Number Verifier](phone_number_verifier.md). If it doesn't match, the web service can return an error and user is returned back to the wizard, where he can correct the input. ### Live vs. Editable { #reg-wizard-live-vs-editable } **Cloud ID** is not entered anywhere in Registration Wizard, the hard-coded cloud ID embedded in the app binary is always used. The trick to provision the editable version is to put the `*` character to the end of the input field in Wizard Step 1. When the app detects trailing `*` character in **username** input param, it removes it and puts it to the end of **cloud ID** input param. For example, if you register with phone number `+15551231234`, you'd enter `+15551231234*`. Note that the trailing `*` is stripped before the value is sent to your scripts, so you don't need to add any special handling there. ### Register New vs. Login Existing The Registration Wizard offers an elegant way how to handle both new users and existing ones. When the external provisioning web service receives the phone number entered by the user, it can check whether the phone number is known and it is an existing user, or if it is a new one. In the second case, it can create a new account and return SIP credentials and other settings in the external provisioning response. ## Web Registration Wizard Web Registration Wizard is the most generic and flexible way of all Initial Screens. When this option is selected, the app shows a full-screen embedded browser and it opens an URL which you can configure. It is then up to you to create anything you want on this web page, the app will serve only as a browser which displays the content you provide. You can ask for username/password, do a 2-factor authentication, add a CAPTCHA check etc. and generally do whatever is needed to collect the two input parameters which are needed to provision the app - **username** and **password**. **Cloud-ID** is always known because it is hard-coded in the app binary. When the process on the web is complete and the input parameters are known, they are passed to the app by navigating the browser to the provisioning link, as described higher on this page. For example, the final page of the reg wizard may contain a link `Start the app`, or the similar link may be openeded via Javascript or HTTP redirect from the server. The app will detect links which use your provisioning scheme (`csc:` by default) and will extract the input parameters from this link. Then it will start the provisioning process. See [Provisioning link](#provisioning-link) above for details. ### Using Client API The URL you choose to show as the initial screen of the Web Registration Wizard is shared among all versions of your app (iOS, Android). You can however use the [Client API](../reporting/intro.md) parameters in your URL to differentiate between platforms. For example, the `%platform%` parameter resolves to either `iOS` or `Android` depending on whether the app is the iOS or Android. You can use this parameter in a URL like `https://your-service.com/csp/%platform%/register`. ### Live vs. Editable { #web-reg-wizard-live-vs-editable } In case of Web Registration Wizard on iOS and Android, the provider itself must find a way how to pass the `*` character in the **cloud ID** part of the provisioning link. One possible way is to do it like the native Registration Wizard - in case `*` is entered as part of **username**, this character is moved to **cloud ID**.