Skip to main content

​
Properties format

The property names must not contain . symbols.

​
Standard properties types

Currently, the following standard properties with types are supported: 
'string',
'number',
'boolean',
'datetime64',
'boolean',
'string[]',
'object'

​
Properties with $type label

The following properties with $type label are supported: 
'currency',
'relation',
'relation[]'
There is a possibility to pass a property object with special attribute name $type and specific value. These kind of special properties allow to adhere to specific use cases.

​
relation or relation[]

The main purpose of this property structure is to establish relationships between two workspace object records. The basic structure of the property shown below: 
client.setRecordProperties([
  {
    id: 'd63506b4-cea0-4fde-9a0e-cb2edee48929',
    slug: 'users',
    properties: {
      set: {
        companies: {
          $type: 'relation',
          object_slug: 'companies',
          domain: 'bigdelta.com',
        },
      },
    },
  },
]);
Provided property companies has a $type attribute with the value relation, indicating that other attributes should be processed differently. The application will create a relationship between the main workspace object record and the records found by the domain in the workspace object identified by the object_slug. If no records are found by domain, no relation will be created. You can also create a relation using the email attribute instead of domain. In this case, the application will link the main workspace object record to those found by matching the email property in the workspace object with the specified object_slug. Again, if no records are found, the relation won’t be created: 
client.setRecordProperties([
  {
    id: 'd63506b4-cea0-4fde-9a0e-cb2edee48929',
    slug: 'users',
    properties: {
      set: {
        companies: {
          $type: 'relation',
          object_slug: 'people',
          email_address: '[email protected]',
        },
      },
    },
  },
]);
Relations can also be created using a recordId. In this case, the application will create a relation with the specified recordId and will even create the corresponding workspace object record if it doesn’t exist. If the recordId belongs to a different type than specified in the object_slug, the application will create a record with the same remote ID in the appropriate workspace object. 
client.setRecordProperties([
  {
    id: 'd63506b4-cea0-4fde-9a0e-cb2edee48929',
    slug: 'users',
    properties: {
      set: {
        companies: {
          $type: 'relation',
          object_slug: 'companies',
          recordId: 'f979110e-76f0-4659-9dd6-412282093967',
        },
      },
    },
  },
]);
Similarly, you can provide multiple relations by using the $type attribute with the value relation[]. The behavior is almost the same as described above, with the key difference being that it creates relations for multiple provided identifiers. Below are examples with slightly different syntax: 
client.setRecordProperties([
  {
    id: 'd63506b4-cea0-4fde-9a0e-cb2edee48929',
    slug: 'users',
    properties: {
      set: {
        companies: {
          $type: 'relation[]',
          object_slug: 'companies',
          domains: ['bigdelta.com'],
        },
      },
    },
  },
]);

client.setRecordProperties([
  {
    id: 'd63506b4-cea0-4fde-9a0e-cb2edee48929',
    slug: 'users',
    properties: {
      set: {
        companies: {
          $type: 'relation[]',
          object_slug: 'people',
          email_addresses: ['[email protected]'],
        },
      },
    },
  },
]);

client.setRecordProperties([
  {
    id: 'd63506b4-cea0-4fde-9a0e-cb2edee48929',
    slug: 'users',
    properties: {
      set: {
        companies: {
          $type: 'relation[]',
          object_slug: 'companies',
          recordIds: ['f979110e-76f0-4659-9dd6-412282093967'],
        },
      },
    },
  },
]);
In all cases above, if the workspace object for the provided object_slug doesn’t exist, it will be created automatically.

​
currency

The main purpose of this property structure is to pass validated currency properties with a specific currency. The basic structure of the property is shown below: 
client.setRecordProperties([
  {
    id: 'd63506b4-cea0-4fde-9a0e-cb2edee48929',
    slug: 'users',
    properties: {
      set: {
        amount: {
          $type: 'currency',
          amount_in_cents: 10,
          currency_code: 'eur',
        },
      },
    },
  },
]);
Provided property amount has a $type attribute with the value currency, indicating that other attributes should be processed differently. The application will validate property attributes format and save currency property. If a certain event is supposed to change related record properties, you can easily do that using the set and set_once parameters when specifying relations, as shown below: 
// `set` - sets the value if it was never set before, or overrides the latest value if one exists.
// `set_once` - sets the value if it was never set before or ignores it otherwise.
client.track({
  event_name: 'My Custom Event',
  properties: { my_property: 'property_value' },
  relations: [{
    object_slug: 'invoice',
    record_id: '63f2164c-2000-4f6c-b377-107368566222',
    set: { 'coupon': 'PROMO10' },
    set_once: { 'invoice_no': 'IN001' }
    }]
});

​
Set record properties

Related record properties could be set when tracking, as described here. However, if you need to set properties separately from the event or manage records that are not related to the event, you can use client.setRecordProperties(), as shown below: 
client.setRecordProperties([
{
  id: 'd63506b4-cea0-4fde-9a0e-cb2edee48929',
  slug: 'users',
  properties: {
    set: {
      name: 'user',
    },
    set_once: {
      email_address: '[email protected]',
    },
  },
},
{
  id: client.getIdentifier('accounts'),
  slug: 'accounts',
  properties: {
    set: {
      title: 'account',
    },
    set_once: {
      owner: '[email protected]',
    },
  },
}]);