Help Center

Menu

Personalization SDK

Configuring the Personalization SDK

Your JavaScript app’s HTML files need to incorporate the Personalization SDK (either for the Datastore local simulator or production service), as well as the main functionality of your app (for example, main.js), which also configures the Data Service, within either the <head/> or <body/> elements of these HTML files.

For a local simulation:

<script src="https://sdk.datastore.squiz.cloud/js/sdk-simulator.js"></script>

For your production service:

<script src="https://sdk.datastore.squiz.cloud/js/sdk.js"></script>

Configuring the Personalization SDK to use your data service in your app:

const settings = {
    serviceURL: '<Your data service URL here>',
    collectionName: ‘assignments',
    collections: {
        base: { path: ‘/' },
        group: { path: ‘group/:groupid'  },
        user: { path: ‘user/:userid' }
    },
    properties: {
        extends: 'extends',
        extendsAll: 'extendsAll',
        extendedBy: 'extendedBy',
        extendedByAll: 'extendedByAll',
    }
};

const datastorePersonalized = new Datastore(settings);

The settings available for the Datastore Personalization SDK are:

Setting Required Simulator only Description Type Example

serviceURL

Yes

No

The Data Service or Simulators URL

String

https://my-data-service.datastore.squiz.cloud

jwtURL

No

No

The URL to the JWT generator being used

String

https://my-jwt.example.com

jwtCallback

No

No

A custom callback function to get a JWT token, must return a promise

Function

 
(payload) => {
    return Promise.resolve();
}

jwtPayload

No

Yes

Optional JWT Payload, required when using the Simulators built in JWT generator

Object

 
{
    “isAdmin”: true
}

collectionName

Yes

No

The collection name that the documents that will be personalized belong to

Sting

my-collection

collections

Yes

No

An object that defines the collections where the personalized documents live. The use of :var1 in the path value of these object defines the variable to be used for determining if the personalized document should be considered

Object

 
collections: {
      base: {
        path: `/`,
      },
      group: {
        path: `/groups/:group1`,
        defaults: {
          group1: `group-1234`,
        },
      },
      user: {
        path: `/users/:userid`
      },

properties

Yes

No

Defines what properties have been defined in the blueprint for extends properties

Object

 
 properties: {
        extends: 'extends',
        extendsAll: 'extendsAll',
        extendedBy: 'extendedBy',
        extendedByAll: 'extendedByAll',
    }

detailedResponse

No

Yes

A flag to return the detailed response of a request e.g. headers, status code etc.

Boolean

true

interceptRequest

No

Yes

An object to flag to return the request information (params, headers, etc) for specified paths before sending the request.

Object

 
{
    “isAdmin”: true
}

failRequests

No

Yes

Fail requests for specific paths with the given error object.

Object

Function list

Function Description

collection(collectionid)

Gets a DatastorePersonalizationCollectionObject reference to perform actions on the personalized collection in the Data Service.

docs(bas, group, user)

Gets a DatastorePersonalizationCollectionsObject reference to perform actions on a personalized collection in the Data Service.

baseDoc(docId, pathValues)

Gets the reference to a specific document in the base collection to perform actions on in the Data Service.

groupDoc(docId, pathValues)

Gets the reference to a specific document in the group collection to perform actions on in the Data Service.

userDoc(docId, pathValues)

Gets the reference to a specific document in the user collection to perform actions on in the Data Service.

baseCollection(pathValues)

Gets the reference to a specific base collection to perform actions on in the Data Service.

groupCollection(pathValues)

Gets the reference to a specific group collection to perform actions on in the Data Service.

userCollection(pathValues)

Gets the reference to a specific user collection to perform actions on in the Data Service.

doc(docid)

Gets a DatastoreDocumentObject reference to perform actions on the document in the Data Service.

overrideDoc(docRef, properties)

Override an existing document property values in a new document in the Data Service.

get(pathValues)

Gets the referenced collection/document.

getPaths(pathValues)

Returns the collection paths.

collection()

Gets a DatastorePersonalizationCollectionObject reference to perform actions on the personalized collection in the Data Service.

Signature

collection(collectionid: string|integer): DatastorePersonalizationCollectionObject

Parameters

collectionid

(string|integer) The collection name as defined in the Blueprint.

Returns

DatastorePersonalizationCollectionObject A DatastorePersonalizationCollectionObject to perform collection requests on.

Example

Consider the situation where we want to get our assignments from a collection to perform actions on, using the Personalization SDK we would do the following.

const students = await datastorePersonalized.collection(`assignments`);

docs()

Gets a DatastorePersonalizationCollectionsObject reference to perform actions on a personalized collection in the Data Service.

Signature

docs(base = true, group = true, user = true): DatastorePersonalizationCollectionsObject

Parameters

base

(boolean) Flag to include documents from the base collection.

group

(boolean) Flag to include documents from the group collection.

user

(boolean) Flag to include documents from the user collection.

Returns

DatastorePersonalizationCollectionsObject A DatastorePersonalizationCollectionsObject to perform document requests on.

Example

Consider the situation where we want to get the most relevant documents from our assignment collections to perform actions on, using the Personalization SDK we would do the following.

const myAssignments = await datastorePersonalized.docs().get({studentID: `abc-123`});

baseDoc()

Gets the reference to a specific document in the base collection to perform actions on in the Data Service.

Signature

baseDoc(docId, pathValues={}): DatastoreDocumentObjectReference

Parameters

docId

(string) The document ID.

pathValues

(Object) Optional path variables to be evaluated.

Returns

DatastoreDocumentObjectReference A DatastoreDocumentObjectReference a reference to the unpersonalized document to make requests on.

Example

Consider the situation where we want to get the unpersonalized document from our assignment collection to perform actions on, using the Personalization SDK we would do the following.

const baseAssignment = await datastorePersonalized.baseDoc(`assignment-1`).get();

groupDoc()

Gets the reference to a specific document in the group collection to perform actions on in the Data Service.

Signature

groupDoc(docId, pathValues={}): DatastoreDocumentObjectReference

Parameters

docId

(string) The document ID.

pathValues

(Object) Optional path variables to be evaluated.

Returns

DatastoreDocumentObjectReference A DatastoreDocumentObjectReference a reference to the group level personalized document to make requests on.

Example

Consider the situation where we want to get the personalized document from our group assignment collection to perform actions on, using the Personalization SDK we would do the following.

const groupAssignment = await datastorePersonalized.groupDoc(`assignment-1`, {groupID: `my-group`}).get();

userDoc()

Gets the reference to a specific document in the user collection to perform actions on in the Data Service.

Signature

userDoc(docId, pathValues={}): DatastoreDocumentObjectReference

Parameters

docId

(string) The document ID.

pathValues

(Object) Optional path variables to be evaluated.

Returns

DatastoreDocumentObjectReference A DatastoreDocumentObjectReference a reference to the user level personalized document to make requests on.

Example

Consider the situation where we want to get the personalized document for a specific user to perform actions on, using the Personalization SDK we would do the following.

const userAssignment = await datastorePersonalized.userDoc(`assignment-1`, {studentID: `abc-123`}).get();

baseCollection()

Gets the reference to a specific base collection to perform actions on in the Data Service.

Signature

baseCollection(pathValues={}): DatastoreCollectionObjectReference

Parameters

pathValues

(Object) Optional path variables to be evaluated.

Returns

DatastoreCollectionObjectReference A DatastoreCollectionObjectReference a reference to the unpersonalized collection to make requests on.

Example

Consider the situation where we want to add an unpersonalized document to our assignment collectiom, using the Personalization SDK we would do the following.

const documentData = { name: `My First Assignment` };
const baseCollection = await datastorePersonalized.baseCollection().add(documentData);

groupCollection()

Gets the reference to a specific group collection to perform actions on in the Data Service.

Signature

groupCollection(pathValues={}): DatastoreCollectionObjectReference

Parameters

pathValues

(Object) Optional path variables to be evaluated.

Returns

DatastoreCollectionObjectReference A DatastoreCollectionObjectReference a reference to the group level personalized collection to make requests on.

Example

Consider the situation where we want to add a personalized document to our course group collection, using the Personalization SDK we would do the following.

const documentData = {
    name: `Group 1 - My First Assignment`,
    extends: `/assignments/assignment-1`
};
const groupCollection = await datastorePersonalized.groupCollection({
    groupID: `group-123`
}).add(documentData);

userCollection()

Gets the reference to a specific user collection to perform actions on in the Data Service.

Signature

userCollection(pathValues={}): DatastoreCollectionObjectReference

Parameters

pathValues

(Object) Optional path variables to be evaluated.

Returns

DatastoreCollectionObjectReference A DatastoreCollectionObjectReference a reference to the user level personalized collection to make requests on.

Example

Consider the situation where we want to add a personalized document to our student assignment collection, using the Personalization SDK we would do the following.

const documentData = {
    name: `My First Assignment`,
    dueDate: `2022-12-02 00:00:00Z`,
    extends: `/group/group-123/assignments/assignment-1`
};
const groupCollection = await datastorePersonalized.userCollection({
    student ID: `abc-123`
}).add(documentData);

doc()

Gets a DatastoreDocumentObject reference to perform actions on the document in the Data Service.

Signature

doc(docid): DatastoreDocumentObject

Parameters

docid

(String) The document id of the document object we want to act upon.

Returns

DatastoreDocumentObject A DatastoreDocumentObject to perform document requests on.

Example

Consider the situation where we want to get a document from our users collection to perform actions on, using the Personalization SDK we would do the following.

const students = await datastorePersonalized.collection(`users`).doc(`abc-123`);

overrideDoc()

Override an existing document property values in a new document in the Data Service.

Signature

overrideDoc(docRef, properties): DatastoreDocumentObject

Parameters

docRef

(DatastoreDocumentObject|DatastorePersonalizedDocumentObject) The document reference to the original document.

properties

(Object) The new document property values to set.

Returns

DatastoreDocumentObject A DatastoreDocumentObject to get the response from the Data Service from.

Example

Consider the situation where we want to override an assignment name for a specific student, using the Personalization SDK we would do the following.

const baseRef = datastore.Personalized.baseDoc(`assignment-1`);
const overridenDoc = await datastorePersonalized.userCollection(`abc-123`)
    .overrideDoc(
        baseRef,
        {
            assignmentName: `Student 123 - Assignment 1`
        }
);

get()

Gets the referenced collection/document.

Signature

get(pathValues): Promise<DatastoreCollectionObject|DatastoreDcoumentObject>

Parameters

pathValues

(Object) Optional path variables to be evaluated.

Returns

Promise<DatastoreCollectionObject|DatastoreDocumentObject> Either a DatastoreCollectionObject or DatastoreDocumentObject to get the response from the Data Service from.

Example

Consider the situation where we want to get the most relevant assignments from our assignment collections for the student with the studentID abc-123,, using the Personalization SDK we would do the following.

const myAssignments = await datastorePersonalized.docs().get({studentID: `abc-123`});

getPaths()

Returns

the collection paths.

Signature

getPaths(pathValues): Array<string>

Parameters

pathValues

(Object) Optional path variables to be evaluated.

Returns

Array<string> An Array<string> of the evaluated collection paths.

Example

Consider the situation where we want to get all the collection paths that our app will use with the given config, using the Personalization SDK we would do the following.

const paths =  datastorePersonalized.docs().getPaths({groupID: `1`, studentID: `abc-123`});

Additional functions available

DatastorePersonalizationCollectionObject

DatastorePersonalizationDocumentObject