User
The SDK allows for the host application to retrieve or update user information.
*Identity: In order to fetch user information, the application must have a valid user (represented by the Identity).
In order to use the SDK, the host application must provide a valid user (Identity). A user is considered valid if it fulfill all the following criteria:
- Created
- Activated
- Not deactivated
The SDK does not verify the status of a user per se, but will report request failures if the user is not in an acceptable state. For example, an unactivated user could collect data (trips), but would not be able to submit those trips, or retrieve any information from the DriveSync server.
Users can be activated via the enrollment file (refer to the enrollment documentation and example provided by the support team). This part will not be covered here, as it relies on the usage of an external XML/CSV file. As a quick summary, the XML/CSV file allows for a user to be created (enrolled) and activated at the same time.
This feature allows for an existing user to be activated. In order to do so, the user needs to submit some information which will allow DriveSync to verify that the user is the correct one, and link that user to a specific ID (similar to the Enterprise external Id in the XML/CSV file for enrollment).
- Activation ID: This must match the activation ID provided during the user enrollment. This value must be unique, and could be considered as some sort of Username.
- Activation Code: This value is generated by DriveSync, and sent to the user via email (the email address must provided during the enrollment). This information should be known only by your user and can be considered as a one-use security token. This value is valid for one activation only, and does expire after a set period of time.
- Email address: This value must match the email address provided during the user enrollment.
- External user Id / JWT SUB: This value is used by DriveSync to match a user from the host application, to a user on the DriveSync server. This is essentially the same information as the "enterprise reference ID" when the activation is done during the enrollment. This value must match the Identity#externalReferenceID value afterward.
Enrolled via XML, activated via SDK
TLDR: When activating, make sure that the current Identity corresponds to the user you want to activate. The identity will be used to link your user, to the DriveSync user being activated. In the XML file sent to DriveSync, the following fields were provided:
- enterprise_id: ent_123
- activation_id: act_123
- enterprise_reference_id: placeholder_value
- email_address: [email protected]
- etc....
The enterprise_reference_id in this scenario is a placeholder value, as it is not necessarily known during the enrollment. Note that if you were to enroll and activate at the same time, the enterprise_reference_id value must be set to the actual value.
When activating, the SDK will link the user corresponding to the current Identity#externalReferenceID to the DriveSync user (when activating via the file, this is done automatically, based on the enterprise_reference_id).
Swift
Kotlin
let service = ActivationService(identity: identity)
service.activate(activationId: activationId,
activationCode: activationCode,
emailAddress: emailAddress then: { result in
switch result {
case .sucess(_):
// activation successful
case .failure(_):
// error
}
})
val service = ActivationService(identity)
service.activate(activationId,
activationCode,
emailAddress,
if (result?.value == null || result.throwable != null) {
// failure
} else {
// Success
val user = result.value
completionHandler(user)
}
}
To fetch user information, one can use the following snippet
Swift
Kotlin
let userService = UserService(identity)
userService.fetch(then: { result in
if let user = result.value {
// Success
completionHandler(user)
} else {
// failure
}
})
val userService = UserService(identity)
userService.fetch { result: Result<User?> ->
if (result?.value == null || result.throwable != null) {
// failure
} else {
// Success
val user = result.value
completionHandler(user)
}
}
The HostApp can update the user information upon success.
To update user information, one can use the following snippet
Swift
Kotlin
let userService = UserService(identity: identity)
userService.update(displayName: displayName,
postalCode: postalCode,
gender: gender,
dateOfBirth: dateOfBirth, then: { result in
switch result {
case .sucess(_):
// update successful
case .failure(_):
// error
}
})
val userService = UserService(identity)
userService.update(displayName,
postcalCode,
gender,
dateOfBirth) { result: Result<User?> ->
if (result?.value == null || result.throwable != null) {
// failure
} else {
// Success
val user = result.value
completionHandler(user)
}
}
Last modified 9mo ago