Configuration: Event and attribute

12min
Summary
This article is about the general composition of an event and an attribute itself. In the following you will learn the structure and the meaning of the individual components and which you can change and how.
This article is structured as follows: 
Structure of events and attributes
Introduction to the placeholder template engine
Example
Structure of events and attributes
The generic structure of an event or attribute is divided into four parts, which you can see in the figure below:
﻿
Summary of the parts:
(1) The "tracking_key"
(2) The „enabled“ property
(3) The key/value pairs of „templates“
(4) The key/value pairs of „parameters“
These four components are described in detail below.
Property "tracking_key"
﻿Property: "tracking_key"﻿
The value of a tracking key is a constant and is used to uniquely assign an event that is fired within the app and its configuration within the "tracking_config.json" file. 
The tracking key itself is always UPPERCASED* and separated by underscores*. So it is important that you always use the constants provided by Purple and do not change these tracking keys in your configuration. 
The events itself are all documented using these tracking keys which you can find in the chapter Tracking Events﻿ and its sub chapters. But some of the events are not documented this way, because of its dependency to the content_type of the related content. 
An example may be <content_type>_OPENED﻿. You can find a detailed description about this topic in the chapter Content types﻿.
If you're having trouble determining what content types your content have, contact Purple's Customer Success or your assigned Purple Project Manager for help.
﻿(*) This definition applies solely to the events provided by Purple. The tracking keys of additional, customer-specific events can be freely defined.
﻿
Configuration summary:
The tracking key maps the app internal event to the event configuration within "tracking_config.json".
Always completely UPPERCASED and separated by underscores.
Do not change these keys.
Property "enabled"
﻿Property: "enabled"﻿
Using this property you may enable or disable this event or attribute. 
There are three cases:
Explicitly set:
true => enable this event for tracking
false => disable this event for tracking
or omitted: 
=> When omitted the app uses the fallback to the
"eventsEnabledByDefault"
"viewsEnabledByDefault"
"purchasesEnabledByDefault"
"attributesEnabledByDefault"
properties used when configuring your tracking service within the "tracking_config.json" file. 
But wait, you never heard about that enable properties? Thats right and all you have to know about this, is described within the chapter Configuration: Enable or disable events or attributes﻿﻿
﻿
Configuration summary:
This property enables or disables this event or attribute.
Three states are possible 
true or false assigned to the enabled property
enabled property is omitted
The key/value pairs of "templates"
﻿Property: "templates"﻿
Each event or attribute has templates. They are used to configure the tracking services. The template names map to the native API of the specific tracking service SDK and each tracking service supports different templates.
Template
A template consists of a template key and a value. The keys must not be changed because they are fixed and used for mapping. The value can be changed to anything you want. 
Depending on the tracking services you use, there may be some restrictions that apply when transmitting the keys and values:
The length of key is restricted
The length of value is restricted
The allowed characters are restricted
﻿
﻿
Structure of a template (key/value pair)
﻿key:﻿
Common template keys are:
"action" for Action events﻿ and Purchase events﻿﻿
"name"  for View events﻿ and Attributes﻿﻿
Other template keys used by specific tracking services are possible. You can find an overview of which templates a specific tracking service supports in the Tracking Services﻿ chapter and its sub chapters.
﻿value:﻿
The value can be changed arbitrarily and can contain placeholders. What placeholders are is described in detail in the Configuration: Enrich event data﻿ chapter.
Configuration summary:
Name of key is fixed and must not be changed.
Values can be changed to anything and can contain placeholders.
Restrictions may exist you have to consider in your configuration.
The key/value pairs of "parameters"
﻿Property: "parameters"﻿
Each event has parameters and they could be used to enrich your event data. Every parameter is sent together with the assigned event. 

Parameter
A parameter consists of a parameter key and a value. The keys and values can be changed to anything you want. However, it may happen that a specific tracking service can restrict this freedom of naming.
Due to the tracking services you use, there may be some restrictions that apply when transmitting the keys and values:
The length of key is restricted
The length of value is restricted
The allowed characters are restricted
The count of parameters itself is restricted
﻿
Structure of a parameter (key/value pair)
﻿key:﻿
Common parameter key names are:
"issue_id" 
"publication_id"
"product_id"
The parameter key name is freely defined. However, is it recommend to follow Purples proposal for its naming convention which is described in detail within the example﻿ in the Configuration: Enrich event data﻿ chapter.
﻿value:﻿
The value can be changed arbitrarily and can contain placeholders. What placeholders are is described in detail in the Configuration: Enrich event data﻿ chapter.
Configuration summary:
Name of key can be changed but is not recommend. You should follow Purple's naming convention.
Values can be changed to anything and can contain placeholders.
Restrictions may exist you have to consider in your configuration.
Introduction to the placeholder template engine
Values of templates and parameters may contain placeholders within the value part and are referenced in the „tracking_config.json“ by using the following syntax:
﻿{{PLACEHOLDER_NAME}}﻿
The placeholder template engine replaces the placeholder with its associated value, which is only available and known at app runtime.
A full description about the functionality of placeholders can be found in chapter Configuration: Enrich event data﻿.
Example
In the following you see a tracking configuration simplified to events and attributes:
Example code 
{
  "default": {
    "events": {},
    "views": {},
    "purchases": {},
    "attributes": {}
  },
  "airship": {
    "events": {
      "STOREFRONT_ISSUE_BOOKMARK_ADDED": {
        "templates": {
          "action": "issue_bookmark_added"
        }
      },
      "ISSUE_DOWNLOADED": {
        "templates": {
          "action": "issue_downloaded"
        }
      },
      "STOREFRONT_SEARCH_PERFORMED": {
        "templates": {
          "action": "search_performed"
        }
      }
    },
    "views": {
      "APP_MENU": {
        "templates": {
          "name": "app_menu"
        }
      }
    },
    "purchases": {
      "STOREFRONT_SUBSCRIPTION_PURCHASED": {
        "templates": {
          "action": "subscription_purchased"
        }
      }
    },
    "attributes": {
      "HAS_ACTIVE_SUBSCRIPTION": {
        "templates": {
          "name": "has_active_subscription"
        },
        "parameters": {
          "tag_group": "subscriptions"
        }
      }
    }
  },
  "firebase": {
    "events": {
      "STOREFRONT_ISSUE_BOOKMARK_ADDED": {
        "templates": {
          "action": "issue_bookmark_added"
        }
      },
      "ISSUE_DOWNLOADED": {
        "templates": {
          "action": "issue_downloaded"
        }
      },
      "STOREFRONT_SEARCH_PERFORMED": {
        "templates": {
          "action": "search_performed"
        }
      }
    },
    "views": {
      "APP_MENU": {
        "templates": {
          "name": "app_menu"
        }
      }
    },
    "purchases": {},
    "attributes": {
      "HAS_ACTIVE_SUBSCRIPTION": {
        "templates": {
          "name": "has_active_subscription"
        }
      }
    }
  }
}
{
  "default": {
    "events": {},
    "views": {},
    "purchases": {},
    "attributes": {}
  },
  "airship": {
    "events": {
      "STOREFRONT_ISSUE_BOOKMARK_ADDED": {
        "templates": {
          "action": "issue_bookmark_added"
        }
      },
      "ISSUE_DOWNLOADED": {
        "templates": {
          "action": "issue_downloaded"
        }
      },
      "STOREFRONT_SEARCH_PERFORMED": {
        "templates": {
          "action": "search_performed"
        }
      }
    },
    "views": {
      "APP_MENU": {
        "templates": {
          "name": "app_menu"
        }
      }
    },
    "purchases": {
      "STOREFRONT_SUBSCRIPTION_PURCHASED": {
        "templates": {
          "action": "subscription_purchased"
        }
      }
    },
    "attributes": {
      "HAS_ACTIVE_SUBSCRIPTION": {
        "templates": {
          "name": "has_active_subscription"
        },
        "parameters": {
          "tag_group": "subscriptions"
        }
      }
    }
  },
  "firebase": {
    "events": {
      "STOREFRONT_ISSUE_BOOKMARK_ADDED": {
        "templates": {
          "action": "issue_bookmark_added"
        }
      },
      "ISSUE_DOWNLOADED": {
        "templates": {
          "action": "issue_downloaded"
        }
      },
      "STOREFRONT_SEARCH_PERFORMED": {
        "templates": {
          "action": "search_performed"
        }
      }
    },
    "views": {
      "APP_MENU": {
        "templates": {
          "name": "app_menu"
        }
      }
    },
    "purchases": {},
    "attributes": {
      "HAS_ACTIVE_SUBSCRIPTION": {
        "templates": {
          "name": "has_active_subscription"
        }
      }
    }
  }
}
﻿
﻿
Updated 20 Oct 2023
Did this page help you?
Structure: Individual events and attributes
Configuration: Enrich event data