Skip to content

Commit 8dd3db8

Browse files
rockwellllrockwellll
authored
Objects (#20)
* update tracking readme * update readme
1 parent 308e73a commit 8dd3db8

File tree

2 files changed

+82
-47
lines changed

2 files changed

+82
-47
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -138,4 +138,4 @@ Hellotext.initialize('HELLOTEXT_BUSINESS_ID', configurationOptions)
138138
| session | A valid Hellotext session which was stored previously. When not set, Hellotext attempts to retrieve the stored value from `document.cookie` when available, otherwise it creates a new session. | String | null |
139139
| autoGenerateSession | Whether the library should automatically generate a session when no session is found in the query or the cookies | Boolean | true |
140140
| forms | An object that controls how Hellotext should control the forms on the page. See [Forms](/docs/forms.md) documentation for more information. | Object | { autoMount: true, successMessage: true } |
141-
| webchat | An object that controls how Hellotext should control the webchat on the page. See [Webchat](/docs/webchat.md) documentation for more information. | Object | { autoMount: true, successMessage: true } |
141+
| webchat | An object that controls how Hellotext should control the webchat on the page. See [Webchat](/docs/webchat.md) documentation for more information. | Object | {} |

‎docs/tracking.md

+81-46
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Hellotext.track('page.viewed', {
6565
Failing to provide valid set of parameters will result in an error object being returned, describing the parameters that did not satisfy the rules.
6666

6767
```javascript
68-
const response = await Hellotext.track('app.installed', { app_parameters: { name: 'My App' } })
68+
const response = await Hellotext.track('app.installed', { object_parameters: { name: null } })
6969

7070
console.log(response.data)
7171
```
@@ -76,31 +76,54 @@ yields
7676
{
7777
errors: [
7878
{
79-
type: 'parameter_not_unique',
79+
type: 'parameter_invalid_empty',
8080
parameter: 'name',
81-
description:
82-
'The value must be unique and it is already present in another object of the same type.',
81+
description: 'This required parameter has an empty value. Provide a valid value for the parameter.',
8382
},
8483
]
8584
}
8685
```
8786

8887
For a complete list of errors types. See [Error Types](https://www.hellotext.com/api#errors)
8988

90-
### Associated objects
89+
### Event parameters
9190

92-
Generally, most actions also require an associated object. These can be of type [`app`](https://www.hellotext.com/api#apps), [`coupon`](https://www.hellotext.com/api#coupons), [`form`](https://www.hellotext.com/api#forms), [`order`](https://www.hellotext.com/api#orders), [`product`](https://www.hellotext.com/api#products) and [`refund`](https://www.hellotext.com/api#refunds).
93-
Aside from [Custom Actions](https://www.hellotext.com/api#create_an_action), which don't require the trackable to be present.
91+
Every tracked event has the following parameters which you can pass to the `track` method:
92+
93+
94+
| Property | Description | Type | Default |
95+
| -------------- |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | ------- |
96+
| **amount** | Monetary amount that represents the revenue associated to this tracked event. | float | `0` |
97+
| **currency** | Currency for the `amount` given in ISO 4217 format. If not specified, the currency default to the business' configured reporting currency. | currency | `USD` |
98+
| **metadata** | Set of key-value pairs that you can attach to an event. This can be useful for storing additional information about the object in a structured format. | hash | `{}` |
99+
| **tracked_at** | Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from `created_at`. | epoch | `null` |
100+
101+
### Associated object parameters
102+
103+
Generally, most actions also require an associated object. These can be of type [`app`](https://www.hellotext.com/api#apps), [`coupon`](https://www.hellotext.com/api#coupons), [`form`](https://www.hellotext.com/api#forms), [`order`](https://www.hellotext.com/api#orders), [`product`](https://www.hellotext.com/api#products) and [`refund`](https://www.hellotext.com/api#refunds), these events require an existing object to be present
104+
in order to be tracked aside from [Custom Actions](https://www.hellotext.com/api#create_an_action), which don't require the trackable to be present.
105+
106+
Associated objects are represented by three possible parameters:
107+
108+
- `object`: An ID of an existing object of the same type. For example, when tracking app events, the `object` must be a previously created app object.
109+
- `object_parameters`: A set of parameters for creating a new object of the same type. For example, when tracking app events, the `object_parameters` must be a set of parameters for creating a new app object.
110+
- `object_type`: An ID or `name` of an existing custom object. Only required when tracking custom objects. Lets Hellotext know which type of object is being tracked. Learn more about [Objects](https://www.hellotext.com/api#objects).
94111

95112
You can create the associated object directly by defining its parameters in a hash:
96113

97114
```javascript
98115
Hellotext.track('order.placed', {
99116
amount: 395.0,
100117
currency: 'USD',
101-
order_parameters: {
102-
amount: '395.00',
118+
object_parameters: {
103119
reference: '654321',
120+
source: 'myshop',
121+
items: [
122+
{
123+
product: 'erA2RAXE',
124+
quantity: 2,
125+
}
126+
]
104127
},
105128
})
106129
```
@@ -112,57 +135,69 @@ For more information about identifiers, view the [Tracking API](https://www.hell
112135
Hellotext.track('product.purchased', {
113136
amount: 395.0,
114137
currency: 'USD',
115-
product: 'erA2RAXE',
138+
object: 'erA2RAXE',
116139
})
117140
```
118141

119142
## List of actions
120143

121-
The following is a complete list of built-in actions and their required associated objects.
144+
The following is a complete list of built-in actions and their required associated objects. Each associated action accepts a possible set of two parameters
145+
146+
122147

123148
| Action | Description | Required Parameter |
124-
| --------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------- |
125-
| **app.installed** | An app was installed. | `app` or [app_parameters](https://www.hellotext.com/api#app) |
126-
| **app.removed** | An app was removed. | `app` or [app_parameters](https://www.hellotext.com/api#app) |
127-
| **app.spent** | A customer spent on an app. | `app` or [app_parameters](https://www.hellotext.com/api#app) |
128-
| **cart.abandoned** | A cart was abandoned. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
129-
| **cart.added** | Added an item to the cart. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
130-
| **cart.removed** | Removed an item from the cart. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
131-
| **coupon.redeemed** | A coupon was redeem by a customer. | `coupon` or [coupon_parameters](https://www.hellotext.com/api#coupons) |
132-
| **form.completed** | A form was completed by the customer. | `form` or [form_parameters](https://www.hellotext.com/api#forms) |
133-
| **order.placed** | Order has been placed. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
134-
| **order.confirmed** | Order has been confirmed by you. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
135-
| **order.cancelled** | Order has been cancelled either by you or your customer. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
136-
| **order.shipped** | Order has been shipped to your customer. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
137-
| **order.delivered** | Order has been delivered to your customer. | `order` or [order_parameters](https://www.hellotext.com/api#orders) |
149+
| --------------------- | -------------------------------------------------------- |---------------------------------------------------------------------------|
150+
| **app.installed** | An app was installed. | `object` or [object_parameters](https://www.hellotext.com/api#app) |
151+
| **app.removed** | An app was removed. | `object` or [object_parameters](https://www.hellotext.com/api#app) |
152+
| **app.spent** | A customer spent on an app. | `object` or [object_parameters](https://www.hellotext.com/api#app) |
153+
| **cart.abandoned** | A cart was abandoned. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
154+
| **cart.added** | Added an item to the cart. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
155+
| **cart.removed** | Removed an item from the cart. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
156+
| **coupon.redeemed** | A coupon was redeem by a customer. | `object` or [object_parameters](https://www.hellotext.com/api#coupons) |
157+
| **form.completed** | A form was completed by the customer. | `object` or [object_parameters](https://www.hellotext.com/api#forms) |
158+
| **order.placed** | Order has been placed. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
159+
| **order.confirmed** | Order has been confirmed by you. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
160+
| **order.cancelled** | Order has been cancelled either by you or your customer. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
161+
| **order.shipped** | Order has been shipped to your customer. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
162+
| **order.delivered** | Order has been delivered to your customer. | `object` or [object_parameters](https://www.hellotext.com/api#orders) |
138163
| **page.viewed** | A page was viewed by a customer. | `url` |
139-
| **product.purchased** | A product has been purchased. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
140-
| **product.viewed** | A product page has been viewed. | `product` or [product_parameters](https://www.hellotext.com/api#products) |
141-
| **refund.requested** | A customer requested a refund. | `refund` or [refund_parameters](https://www.hellotext.com/api#refunds) |
142-
| **refund.received** | A refund was issued by you to your customer. | `refund` or [refund_parameters](https://www.hellotext.com/api#refunds) |
164+
| **product.purchased** | A product has been purchased. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
165+
| **product.viewed** | A product page has been viewed. | `object` or [object_parameters](https://www.hellotext.com/api#products) |
166+
| **refund.requested** | A customer requested a refund. | `object` or [object_parameters](https://www.hellotext.com/api#refunds) |
167+
| **refund.received** | A refund was issued by you to your customer. | `object` or [object_parameters](https://www.hellotext.com/api#refunds) |
143168

144169
You can also create your **[own defined actions](https://www.hellotext.com/api#actions)**.
145170

146-
## Additional Properties
171+
### Tracking Custom Actions
147172

148-
You can include additional attributes to the tracked event, additional properties must be included inside the `metadata` object:
173+
Once you have created a custom action, you track it by specifying the action's name. Custom actions do not require an associated object to be present in order to be tracked.
174+
However, it's possible to track custom actions alongside existing Objects, or new objects you introduce.
149175

150176
```javascript
151-
Hellotext.track('product.purchased', {
152-
amount: 0.2,
153-
currency: 'USD',
154-
metadata: {
155-
myProperty: 'custom',
156-
},
157-
tracked_at: 1665684173,
177+
// Custom Action without an associated object
178+
179+
Hellotext.track('appointment.booked')
180+
181+
// Custom Action with an existing custom object instance.
182+
183+
Hellotext.track('appointment.booked', {
184+
object_type: 'appointment',
185+
object: 'erA2RAXE',
158186
})
159-
```
160187

161-
### List of additional attributes
188+
// Custom Action with a new custom object instance.
189+
Hellotext.track('appointment.booked', {
190+
object_type: 'appointment',
191+
object_parameters: {
192+
room: 'AA-101',
193+
booked_at: 1632313200,
194+
}
195+
})
162196

163-
| Property | Description | Type | Default |
164-
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
165-
| **amount** | Monetary amount that represents the revenue associated to this tracked event. | float | `0` |
166-
| **currency** | Currency for the `amount` given in ISO 4217 format. | currency | `USD` |
167-
| **metadata** | Set of key-value pairs that you can attach to an event. This can be useful for storing additional information about the object in a structured format. | hash | `{}` |
168-
| **tracked_at** | Original date when the event happened. This is useful if you want to record an event that happened in the past. If no value is provided its value will be the same from `created_at`. | epoch | `null` |
197+
// Custom Action with a builtin object instance.
198+
199+
Hellotext.track('appointment.booked', {
200+
object_type: 'product',
201+
object: 'erA2RAXE',
202+
})
203+
```

0 commit comments

Comments
 (0)