Correct and up to date customer data makes or breaks your ability to make efficient use of Bloomreach Engagement. That is why we allow multiple systems to run in parallel for maintaining your customer properties. However, if you are not careful with working with your data, some of them might get lost or replaced by outdated pieces of information. One of the cases, where this corruption might occur, is during imports or it might happen during postponed tracking by the mobile SDK. To prevent this from happening, we have implemented the customer properties synchronization.

Customer properties synchronization in practice means that the customer updates and imports are timestamped. This means that Bloomreach Engagement will not only track your customer's properties but also the time of its last update. This enables us to prevent the previously described undesired behavior by comparing the timestamps during updates and only overwriting the properties if the value is indeed new. In other words, when an update with newer timestamp will be requested, Bloomreach Engagement will overwrite the property. On the other hand, if an update with older timestamp is present, we won’t overwrite the property, since we already have the fresher version.

Changes to working with data

The customer properties synchronization also brings a few changes to how you can work with our data.

Fetching customer properties

The already existing API route GET /api/customers/<customer_id> for fetching customer properties was modified to support a new GET argument ?include_timestamps=1.

When the include_timestamps is present in the request and equal to 1, the output format of the route will include a UNIX timestamp corresponding to the last update for each customer property. If this information is not present (it was not tracked in the past), the value will be -1.

{
  “properties”: {
    “first_name”: {“value”: “Marian”, “last_update”: 1570001049},
    “last_name”: {“value”: “Galik”, “last_update”: -1}
  }
}

However, when the include_timestamps in the request is not present or is set to 0, the output format of the route won’t change:

{
  “properties”: {
    “first_name”: “Marian”,
    “last_name”: “Galik”
  }
}

Updating customer properties from UI

Updating properties from the UI will automatically add the timestamp for you.

Importing customer properties

The mapping step in import wizard now includes a voluntary field called update_timestamp. It behaves similarly to the timestamp in event imports. The difference is that this field is not mandatory. When the field is not present, Bloomreach Engagement will use the current timestamp evaluated at the time when the import execution has been started.

The mapping model previously contained the following.

{
  “properties”: [{
    “from_column”: “meno”,
    “to_property”: “first_name”,
    “type”: “string”
  }],
  “ids”: [{
    “from_column”: “idecko”,
    “to_id”: “registered”
  }],
  “constant_columns”: [],
  “timezone”: “UTC”
}

However, it will now optionally also include the “update_timestamp”: {“from_column”: “update_timestamp”}, line.
Hence the model might look like this:

“properties”: [{
    “from_column”: “meno”,
    “to_property”: “first_name”,
    “type”: “string”
  }],
  “update_timestamp”: {“from_column”: “update_timestamp”},
  “ids”: [{
    “from_column”: “idecko”,
    “to_id”: “registered”
  }],
  “constant_columns”: [],
  “timezone”: “UTC”
}

The field from_column refers to a field from the data, that contains the update timestamp. The field can refer to a constant column as well. All the formats that are currently supported on the timestamp field of event imports are also supported on the update_timestamp field.

Tracking API and SDKs

Tracking API accepts additional optional parameter inside the customers command called update_timestamp. When this argument is present, it will be applied to all the properties from the particular command.

POST /track/v2/projects/00000000-0000-0000-0000-000000000000/batch HTTP/1.1
Content-Type: application/json
Host: example.com

{
   "commands": [
       {"name": "system/time"},
       {"name": "system/cookie"},
       {"name": "customers",
           "data": {
               "customer_ids": {"registered": "mgalik"},
               "properties": {"first_name": "Marian", "last_name": "Galik"},
               "update_timestamp": 1570001049
           }
       }
   ]
}

📘

SDK changes

The Bloomreach Engagement SDK does not change with Customer properties synchronization. The changes above will suffice for the mobile SDKs to be able to handle offline connections properly.