Application
Application (app) component is responsible for all of the commands that are related to mobile application configuration management.
Force Upgrade
Copilot.cx allows you to manage your application versions and easily communicate to users that an upgrade is required. This feature is useful in case of a new business or legal requirement, a critical issue with a deployed version, or a security issue (just to name a few use cases).The force upgrade state should correspond to the appropriate user interface with a message to the users and a call to action with a link to the relevant store to upgrade. The force upgrade process is triggered within Copilot.cx Admin interface for either Android, iOS or both.
💡This is may be the first endpoint you would like to call when your application is loading. In case that this version should be upgraded, a common practice would be disabling any client<->server interaction as one of the use cases is the server cannot support the client anymore hence should be upgraded.
💡How application version is determined - Android uses the versionName property, iOS uses the
CFBundleShortVersionStringfrom app’s info.plist file.
💡Version comparison - will be made according to OSGI semantic versioning. Meaning application version can be represented in up to 4 compartments: major.minor.micro.qualifier (qualifier is a string. For example
1.2.3.BUILD-2018-06-04). All compartments will be compared as integers until reaching the last compartment and it will be compared as string. For example, if the client application is1.2.3.build8and minimal supported version is1.2.2.build7the client application won’t be requested to upgrade.
Result model
Result of type AppVersionStatusModel contains:
VersionStatus - Enum which contains the following cases:
OK- The current version is up to date, no need for an updateNotSupported-The current version is deprecated and requires an updateNewVersionRecommended- A newer version has been found but the update is not required
Result error
Below are the possible errors you can receive in case of CheckAppVersionStatusError type failure:
AppVersionBadFormat- Please check the application version set in yourinfo.plistandbuild.gradlefiles. Refer versioning.ConnectivityError- A communication failure occurred while executing this command.GeneralError- A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
Code sample
Copilot.instance
.manage
.sphere
.app
.checkAppVersionStatus()
.build()
.execute { (result) in
switch result {
case .success(let appVersionStatus):
switch(appVersionStatus.versionStatus) {
case .ok:
break
case .notSupported:
break
case .newVersionRecommended:
break
}
case .failure(error: let checkAppVersionError):
switch(checkAppVersionError) {
case .appVersionBadFormat(let debugMessage):
break
case .connectivityError(let debugMessage):
break
case .generalError(let debugMessage):
break
}
}
}
Copilot.getInstance()
.Manage
.Sphere
.App
.checkAppVersionStatus()
.build()
.execute(new RequestListener<AppVersionStatusModel, CheckAppVersionStatusError>() {
@Override
public void success(AppVersionStatusModel response) {
switch (response.getVersionStatus()) {
case OK:
break;
case NotSupported:
break;
case NewVersionRecommended:
break;
case Unknown:
break;
}
}
@Override
public void error(CheckAppVersionStatusError error) {
switch (error) {
case AppVersionBadFormat:
break;
case ConnectivityError:
break;
case GeneralError:
break;
}
}
});
Copilot.getInstance()
.Manage
.Sphere
.App
.checkAppVersionStatus()
.build()
.execute(object : RequestListener<AppVersionStatusModel, CheckAppVersionStatusError?> {
override fun success(response: AppVersionStatusModel) {
when (response.versionStatus) {
VersionStatus.OK -> {}
VersionStatus.NotSupported -> {}
VersionStatus.NewVersionRecommended -> {}
VersionStatus.Unknown -> {}
}
}
override fun error(error: CheckAppVersionStatusError?) {
when (error) {
CheckAppVersionStatusError.AppVersionBadFormat -> {}
CheckAppVersionStatusError.ConnectivityError -> {}
CheckAppVersionStatusError.GeneralError -> {}
}
}
})
Configuration
Fetch the configuration in order to receive the legal documents associated with your application. A legal document contains an url and a version. The document urls are controlled from Copilot.cx Admin web UI.
💡You might use the url to display the content of the relevant property in a web view, so the user can approve or consult them.
💡You also might decide to trigger the terms and conditions approval flow again in your app in case the document version has changed.
💡 Read about how to approve terms of use here.
Result model
Result of type Configuration contains:
PrivacyPolicy- The legal document for the privacy policy. Contains the legal document URL and its version.TermsOfUse- The legal document for the terms of use. Contains the legal document URL and its version.Faq- The legal document for the faq. Contains the legal document URL and its version.
Result error
Below are the possible errors you can receive in case of FetchConfigurationError type failure:
ConnectivityError- A communication failure occurred while executing this command.GeneralError- A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
Code sample
Copilot.instance
.manage
.sphere
.app
.fetchConfig()
.build()
.execute { (response) in
switch response {
case .success(let configuration):
break
case .failure(error: let fetchConfigurationError):
switch(fetchConfigurationError) {
case .connectivityError(let debugMessage):
break
case .generalError(let debugMessage):
break
}
}
}
Copilot.getInstance()
.Manage
.Sphere
.App
.fetchConfiguration()
.build()
.execute(new RequestListener<SystemConfigurationModel, FetchConfigurationError>() {
@Override
public void success(SystemConfigurationModel response) {
}
@Override
public void error(FetchConfigurationError error) {
switch (error) {
case ConnectivityError:
break;
case GeneralError:
break;
}
}
});
Copilot.getInstance()
.Manage
.Sphere
.App
.fetchConfiguration()
.build()
.execute(object : RequestListener<SystemConfigurationModel?, FetchConfigurationError?> {
override fun success(response: SystemConfigurationModel?) {}
override fun error(error: FetchConfigurationError?) {
when (error) {
FetchConfigurationError.ConnectivityError -> {}
FetchConfigurationError.GeneralError -> {}
}
}
})
Password policy
Validating passwords is required in case of user registration. Passwords should be validated according to your application’s policy. The password policy rules are fetched by executing the fetchPasswordPolicy command.
This command will allow getting a set of rules to be enforced on the password the user types when registering to your application e.g. minimal length or existence of special characters.
In case you do not validate the password prior to the registration, and it does not comply with policy rules, you will receive an error passwordPolicyViolation when you will execute the signup command.
💡 You can fetch the rules before loading your registration screen and then use them to validate the password typed by the user on the fly. Alternatively, you might fetch them at the time the user tapped sign-up, and use the rules and validate the user password before executing the signup request.
Result model
Result of type PasswordRules contains:
PasswordRulesis a collection ofPasswordRuleobjects. Each password rule contains theruleIdand thenumericValue:RuleId- The ruleId can be one of the following:MinimumLengthMaximumLengthMaximumConsecutiveIdenticalComplexity_MinimumUpperCaseComplexity_MinimumLowerCaseComplexity_MinimumDigitsComplexity_MinimumSpecialCharsRejectWhiteSpace
NumericalValue- Most of thePasswordRuleIdcan be represented by a number, for exampleminimumLengthcould have a value of 5, meaning that the password cannot be shorter than 5 characters.isValid(String password)- method used to check if the password is valid or not.
💡 This mechanism enables the application to comply with OWASP standards and best practices implementing proper password strength control (for more information please refer OWASP)
💡In the case the type of the
PasswordRuleIdis abooleanlike therejectWhiteSpace, thenumericalValuereturned will be 0.
Result error
Below are the possible errors you can receive in case of FetchPasswordRulesPolicyError type failure:
ConnectivityError- A communication failure occurred while executing this command.GeneralError- A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
Code sample
Copilot.instance
.manage
.sphere
.app
.fetchPasswordPolicyConfig()
.build()
.execute { (response) in
switch response {
case .success(let rules):
break
case .failure(error: let fetchPasswordPolicyError):
switch(fetchPasswordPolicyError) {
case .connectivityError(let debugMessage):
break
case .generalError(let debugMessage):
break
}
}
}
Copilot.getInstance()
.Manage
.Sphere
.App
.fetchPasswordPolicyConfiguration()
.build()
.execute(new RequestListener<List<PasswordRule>, FetchPasswordRulesPolicyError>() {
@Override
public void success(List<PasswordRule> response) {
// Password policy rules fetched with success
}
@Override
public void error(FetchPasswordRulesPolicyError error) {
switch (error) {
case ConnectivityError:
break;
case GeneralError:
break;
}
}
});
Copilot.getInstance().Manage
.Sphere
.App
.fetchPasswordPolicyConfiguration()
.build()
.execute(object : RequestListener<List<PasswordRule?>?, FetchPasswordRulesPolicyError?> {
override fun success(response: List<PasswordRule?>?) {
// Password policy rules fetched with success
}
override fun error(error: FetchPasswordRulesPolicyError?) {
when (error) {
FetchPasswordRulesPolicyError.ConnectivityError -> {}
FetchPasswordRulesPolicyError.GeneralError -> {}
}
}
})