Adding Datastore

Read this article to understand how you can extend the personalization framework using Datastore.

Overview

The personalisation framework simplifies how you integrate with Datastore by offering baseline functionality that is restricted by design.

By restricting functionality to only critical integration points, you can confidently extend Datastore by adding integration points directly into your application, rather than within the personalisation framework code itself.

When is data updated?

Datastore does not replace trait local storage; rather, it supplements local storage by adding a permanent data storage layer.

Each time a trait is updated in local storage, it is also updated at the Datastore layer. When the changePersona() function is called, Datastore also records this, and the data is saved in an array.

If you find this level of trait functionality is not suitable for your data storage requirements, you can write an application-specific code that implements a different permanent data storage mechanism.

Installing

For development and testing, you must simulate the Datastore locally using Docker and the personalisation framework blueprint.

Follow steps two to four on the Squiz Marketplace personalization blueprint page:

  • Step 2: Learn how to use Datastore

  • Step 3: Simulate and test the personalization blueprint

  • Step 4: Add your blueprint to the Squiz Experience Cloud.

The marketplace listing refers back to documentation in this section. Use the marketplace documentation to guide you through the rest of the steps.

Configure the framework to work with Datastore

Remember to change these settings when you deploy the blueprint to production.

The Datastore simulator command-line interface provides you with a base URL for the API once you have it set up and running locally. Add this URL into the configuration for the personalisation framework.

  1. Load your Matrix instance.

  2. Navigate to the Personalisation settings screen.

    1. In the General settings tab, add the URL provided by the simulator.

    2. In the Datastore environment field, set the correct personalization environment to load the Development version of the Datastore SDK.

  3. Click Save.

Adding traits

Consult the account owner if you need to store sensitive information.

See the Datastore privacy and security documentation for guidance on what type of data is suitable to store in Datastore.

The Datastore blueprint includes common API methods for storing user traits as well as storing a user’s Opted Persona. Opted Persona is when a user has specifically opted into a persona using the changePersona() function.

To add more custom traits to Datastore, follow the provided convention in the user schema.

The trait names in the personalisation framework must match those in the schema.
Example user trait property in the user schema
"siteVisits": {
    "title": "Site visits",
    "description": "Increments on each page load of the site.",
    "type": "integer",
    "example": 10,
    "default": 1
}

Retrieving a single record

The framework offers a GET method to retrieve a single user using the API.

You can use this method to resume a user’s session provided you know the UUID. You can implement this method inside your code, providing it is loaded after the Personalisation Framework’s Javascript.

Retrieve a single user document using the SDK
dataStore.collection('users')
   .doc('6d833c5c-b11d-48cc-ba84-de4b4bdf673f')
   .get()
   .then((document) => console.log(document));

Deleting users

The framework offers a DELETE method to delete a single user document or all user documents in a collection.

Delete a single user based on their UUID
/**
 * Delete a user document
 * @param {string} id: the document's uuid
 */
function deleteUserRecord(id) {
    // Delete the user document
    dataStore.collection('users').doc(id).delete();
}
Delete all user documents in the user collection
/**
 * Delete all
 * @param {string} id: the document's uuid
 */
function deleteAll() {
    // Delete all user documents in the user collection
    dataStore.collection('users').get().then((collection) => {
        collection.forEach((item) => {
            deleteUserRecord(item.userid);
        });
    });
}

© 2015-2020 Squiz Pty Ltd