Comment on page
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).
Activation
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.
Activating while enrolling
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.
Activating a user via the SDK
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).
Required information
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.
Concrete example
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)
    }
}
Fetch user information
Parameters:
expansions: The expansions applied for a user
Expansions options are below:
ASSOCIATEDUSERS
SHAREDINFORMATION
ASSOCIATEDACCOUNT
CUSTOMFIELDS
ROLE
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)
    }
}
Update user information
The HostApp can update the user information upon success.
Concrete example
To update user information, one can use the following snippet
Swift
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
    }
})
DriveSync Portal
Device
Last modified 2mo ago