DXDataClient

This class is responsible for making requests to the DX data API.

public final class DXDataClient

The DXDataClient class allows you to create and update buckets to store your app's data. Buckets can be created for a single user for private data. or for multiple users, allowing them to access shared data. Buckets are essentially JSON objects with key-value pairs and can be updated by creating and writing to a new key, or overwriting an existing one.

You will need to enable the "Lightning Database" scope for your app in the developer dashboard before using the data API.

Properties

public static let shared: DXDataClient

Singleton instance of DXDataClient. You will access all the available DXDataClient methods through this instance.

Methods

readPrivateData

public func readPrivateData(
    userId: String? = nil, 
    completion: @escaping (_ error: Error?, _ data: Any?) -> Void
) -> Void

Read a user's private app data.

Parameter	Type	Description
userId	String?	User id for the owner of the app data to retrieve. A user can only query for his or her own app data of the app data of their kids' accounts.
completion	(Error?, Data?) -> Void	The closure invoked when the request finishes.
error	Error?	The error returned for an unsuccessful request.
data	Any?	The private app data returned for a successful request.

writePrivateData

public func writePrivateData<V: Codable>(
    atKey key: String, 
    withValue value: V, 
    userId: String? = nil, 
    _  completion: ((_ error: Error?, _ data: Any?) -> Void)?
) -> Void

Update a user's private app data.

Parameter	Type	Description
atKey	String	Location in app data to update, using dot object notation.
withValue	V: Codable	Value to insert or update at the location specified by the key parameter. This can be any valid JSON data.
userId	String?	User id for the owner of the app data to update. A user can only update his or her own app data or the app data of their kids' accounts.
completion	(Error?, Any?) -> Void	The closure invoked when the request finishes.
error	Error?	The error returned for an unsuccessful request.
data	Any?	The update data returned for a successful request.

create

public func create(
    bucketNamed bucketName: String, 
    includingUsers users: [String] = [], 
    _ completion: ((_ error: Error?) -> Void)?
) -> Void

Create a named bucket and specify what users have access to it. By default, the user creating the bucket (the currently authenticated user) will have access to the bucket.

Parameter	Type	Description
bucketNamed	String	Name given to the bucket.
includingUsers	[String]	An array of DX user ids representing who will have access to the bucket; by default, the user creating the bucket will have access.
completion	((Error?) -> Void)?	The closure invoked when the request finishes.
error	Error?	The error returned for an unsuccessful request.

write

public func write<V: Codable>(
    toBucket bucketName: String, 
    atKey key: String, 
    withValue value: V, 
    _  completion: ((_ error: Error?, _ data: Any?) -> Void)?
) -> Void

Write data to a bucket at a key. If key is an empty String, the bucket will be overwritten with the value provided. If the key does not exist in the bucket, it will be created in the bucket as a key-value pair. All data written to a bucket has to conform to Swift's Codable protocol (introduced in version 4.2), as it will otherwise cause an error when attempting to serialize the value to JSON. For more information on Codable, check out this link.

Attempting to write to a bucket that hasn't been created will return an error.

Parameter	Type	Description
toBucket	String	Name of the bucket being written to.
atKey	String	Key in the bucket where the data will be written. For nested keys, use a period-separated string, e.g. "root.sub".
withValue	V: Codable	The value being written to the bucket.
completion	((Error?, Any?) -> Void)?	The closure invoked when the request finishes.
error	Error?	The error returned for an unsuccessful request.
data	Any?	The newly updated bucket returned for an unsuccessful request.

read

public func read(
    fromBucket bucketName: String, 
    atKey key: String? = nil, 
    _ completion: @escaping (_ error: Error?, _ value: Any?) -> Void
) -> Void

Read data from a bucket. If a key is provided, it will read data from that key in the bucket.

Attempting to read from a bucket that hasn't been created will return an error.

Parameter	Type	Description
fromBucket	String	The name of the bucket being read from.
atKey	String?	If provided, will read data from the bucket at this key; defaults to nil, which will return the entire bucket. For nested keys, provided a period-separated string.
completion	(Error?, Any?) -> Void	The closure invoked when the request finishes.
error	Error?	The error returned for an unsuccessful request.
value	Any?	The data returned for a successful request. If no key is provided, the entire bucket will be returned, otherwise, the data at the key in the bucket will be returned.

readAllBuckets

public func readAllBuckets(
    _ completion: @escaping (_ error: Error?, _ buckets: [String]?) -> Void
) -> Void

Read all buckets that the current user has access to. Will return an array of the buckets' names.

Parameter	Type	Description
completion	(Error?, [String]?) -> Void	The closure invoked when the request finishes.
error	Error?	The error returned for an unsuccessful request.
buckets	[String]?	An array of the names of the buckets the current user has access to.

delete

public func delete(
    fromBucket bucketName: String, 
    atKey key: String, 
    _ completion: ((_ error: Error?, _ bucket: Any?) -> Void)?
) -> Void

Delete a key in the bucket, including all nested data at that key.

Attempting to delete a key in a bucket that hasn't been created will return an error.

Parameter	Type	Description
fromBucket	String	Name of the bucket the key is being deleted from.
atKey	String	The key in the bucket that is being deleted.
completion	((Error?, Any?) -> Void)?	The closure invoked when the request finishes.
error	Error?	The error returned for an unsuccessful request.
bucket	Any?	The updated bucket returned for a successful request.

delete

public func delete(
    bucketNamed bucketName: String, 
    _ completion: ((_ error: Error?) -> Void)?
) -> Void

Delete an entire bucket.

Attempting to delete a bucket that hasn't been created will return an error.

Parameter	Type	Description
bucketNamed	String	Name of the bucket to delete.
completion	((Error?) -> Void)?	The closure invoked when the request finishes.
error	Error?	The error returned for an unsuccessful request.