Using the new local datastores feature

The Sync and Datastore SDK has since been deprecated, but the 3.0 release of the Datastore API introduced a preview feature worth understanding: local datastores. It answers a question developers had raised since the API's first release — how to handle users who have no Dropbox account. With local datastores, a single body of code works whether or not the user has signed in. Signed out, all data is written locally. Once a Dropbox account is linked, that data is stored in the cloud and synced across devices.

The Tasks example app bundled with Datastore API 3.0 demonstrates the typical flow. A new user's data starts out entirely in a local datastore. If the user later chooses to back the data up to Dropbox or sync it between devices, they link an account, and the app migrates the local datastore into that account.

Switching from a local datastore to a linked account

The sample below is adapted from the Tasks sample shipped with the iOS and Android Datastore SDKs and shows the switch from local storage to a linked Dropbox account.

Android

// If the user has linked a Dropbox account for the first time...
if (justLinked) {
    // Perform a one-time migration to move from the local datastore to a remote one.
    mDatastoreManager = mLocalManager.migrateToAccount(mDbxAcctMgr.getLinkedAccount());
    mLocalManager = null;
    mDatastore = mDatastoreManager.openDefaultDatastore();
}
if (null == mDatastoreManager) {
    // If there's a linked account, use that.
    if (mDbxAcctMgr.hasLinkedAccount()) {
        mDatastoreManager = DbxDatastoreManager.forAccount(mDbxAcctMgr.getLinkedAccount());
    }
    // Otherwise, use a local datastore.
    else {
        mDatastoreManager = DbxDatastoreManager.localManager(mDbxAcctMgr);
    }
}

iOS

// If the user has linked a Dropbox account for the first time...
if (_justLinked) {
    if (_localDatastoreManager && self.account) {
        // Perform a one-time migration to move from the local datastore to a remote one.
        [_localDatastoreManager migrateToAccount:self.account error:nil];
        _localDatastoreManager = nil;
    }
}
if (!_store) {
    // If there's a linked account, use that.
    if ([[DBAccountManager sharedManager] linkedAccount]) {
        _store = [DBDatastore openDefaultStoreForAccount:self.account error:nil];
    // Otherwise, use a local datastore.
    } else {
        _store = [DBDatastore openDefaultLocalStoreForAccountManager:[DBAccountManager sharedManager]
                                                               error:nil];
    }
}

Preview status

Local datastores are a preview feature, not a production-ready one. Feedback belongs on the developer forum, and the documentation's list of known issues is required reading before adoption. A production-ready release is planned.