What is the purpose of persistence in regard to custom properties?

With the Piano Analytics SDK, you can tag custom properties without using a specific method as the “tag first” approach is used. You can tag your custom properties as in the example below:

pa.sendEvent('page.display', { page: pagename, custom_prop: value })

However, if you need to send this property on several events during the same page load, you can use pa.setProperty() (this method allows adding a persistent notion to your properties):

pa.setProperty('custom_prop', value, { persistent: true })

How persistence works

Persistence in the Piano Analytics SDK means the property value is stored by the SDK and automatically appended to subsequent events until the SDK is reloaded (for example, on a full page reload). In other words:

• Persistence is limited to a single page load in typical web implementations.

• When the user navigates to a new page, and the SDK is re-initialized, persistence is lost and must be defined again if needed.

• Persistence applies within the same tracker/SDK instance (if a new instance is created without the property, the property will not be included).

persistent option values

The persistent parameter can take the following values:

• persistent: true adds this custom property to all subsequent events (during the same page load, within the same SDK instance).

• persistent: false applies the property to only the next event sent after this method is called.

Limiting persistence to specific events

You can define which events are going to be filled with the custom property using the events parameter.

Example:

pa.setProperty('custom_prop', value, {
  persistent: true,
  events: ['page.*', 'click.navigation']
})

In the example above, only the events beginning with page. and the click.navigation events will be filled with the property custom_prop. Other events (for example click.action, click.download, click.exit) will not receive it.

Applying persistence to all events

If you want the property to be applied to every subsequent event type, you can omit the filter or pass an empty events array:

pa.setProperty('live_id', 'value', { persistent: true, events: [] })

Setting multiple persistent properties at once

If you want to send a list of properties you can use pa.setProperties().

You can also mix persistent and non-persistent behavior by calling pa.setProperties() multiple times with different options, depending on which properties should carry over to subsequent events.

Example:

pa.setProperties(
  { custom_property: 'value' },
  { persistent: true, events: ['page.*', 'click.*'] }
)