Customer properties synchronization

Correct and up to date customer data makes or breaks your ability to make efficient use of Exponea. 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.

To illustrate the issue further, consider the following example.

We can start an import at 8:00 which will end at 10:00. This import contains a snapshot of data from your system as they looked at 8:00 however since the actual execution span is 2 hours, by that time Exponea could have updated some customer property form the real-time tracking with fresher data and the import could have overwritten them with the old version from import.

Customer properties synchronization in practice means that the customer updates and imports are timestamped. This means that Exponea 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, Exponea 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, Exponea 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 Async API, Async API worker, and SDKs

AsyncAPI accepts additional optional parameter inside the customers command called update_timestamp. When this argument is present, it will be propagated to AsyncAPI worker and back kafka.

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
           }
       }
   ]
}

This parameter will be applied to all the properties from the particular command.

SDK changes

The Exponea 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.

Updated 2 months ago

Customer properties synchronization


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.