{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","params":[],"results":{"codes":[]}},"next":{"description":"","pages":[]},"title":"Track an Event","type":"fn","slug":"track","excerpt":"Tracks an event for the current user","body":"[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"This page documents a no-longer supported version of the Boomtrain JavaScript Library (versions 4.x and below). The new `p13n.js` library, documented [here](https://boomtrain.readme.io/v1/docs/p13njs-getting-started) is the currently supported library for integrating with ZetaHub.\",\n  \"title\": \"Deprecated API Warning\"\n}\n[/block]\nEvents (also known as *activities*) are used to indicate that a user performed a particular action. These events will appear in your user's profile as recent history, and can be used to create behaviors for triggers and segmentation in the Boomtrain Marketing Engine. As well, these events act as signals for Boomtrain's personalization systems to generate insights and predictive recommendations for your campaigns.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"_bt.track(event_type, [attributes], [callback]);\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe `track` call has the following fields:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`event_type`\",\n    \"0-1\": \"String\",\n    \"0-2\": \"The name of the event, e.g. \\\"viewed\\\", \\\"liked\\\", \\\"shared\\\". See Event Types below for more details.\",\n    \"1-0\": \"`attributes` *optional*\",\n    \"1-1\": \"Object\",\n    \"1-2\": \"An object containing key:value pairs indicating attributes to be  tracked as metadata in this event. See Attributes below for more information.\",\n    \"2-0\": \"`callback` *optional*\",\n    \"2-1\": \"Function\",\n    \"2-2\": \"A function that is executed after this function completes and the event has been tracked. **Note:** If an event results in the user leaving the page, be sure to not navigate away until this `track` call finishes. You can ensure this by adding the page navigation call into the function specified here.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Event Types\"\n}\n[/block]\nWhile you may specify any `event_type`, a few are standardized and specially handled by Boomtrain:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Event Type\",\n    \"h-2\": \"Description\",\n    \"h-1\": \"Special Attributes\",\n    \"0-0\": \"`viewed`\",\n    \"0-2\": \"Indicates a user has viewed a page. Automatically triggered on page load when `autoTrack` is on (as it is by default). See [Getting Started](doc:getting-started-2) for full details.\",\n    \"1-0\": \"`liked`\",\n    \"2-0\": \"`shared`\",\n    \"3-0\": \"`commented`\",\n    \"4-0\": \"`purchased`\",\n    \"5-0\": \"`updated_cart`\",\n    \"1-2\": \"Indicates an explicit preference for the current page by the user.\",\n    \"0-1\": \"`resource_id` - If provided, uses this value instead of the current page (default) as the viewed resource.\",\n    \"1-1\": \"`score` - When a like is paired with a multi-point scale, provide an integer representation of the value provided. If the action indicated is a \\\"dislike\\\" or *negative* preference, use `-1`.\",\n    \"2-1\": \"`resource_id` - If provided, uses this value instead of the current page (default) as the \\\"object\\\" of the share.\\n`target_user_id` - The `user_id` of the target of the share.\",\n    \"2-2\": \"Indicates a user has shared the current page/resource (or the one indicated by `resource_id`) with another user. Emit this once per distinct target user/resource. That is, if a user shares one article with 4 target users, trigger this event 4 times with each `target_user_id` specified.\",\n    \"3-1\": \"`resource_id` - If provided, uses this value instead of the current page (default) as the \\\"object\\\" that was commented on.\\n`comment_text` - The text of the comment.\",\n    \"3-2\": \"Indicates a user has commented on the current page/resource (or the one indicated by `resource_id`).\",\n    \"4-1\": \"\",\n    \"4-2\": \"Indicates a user has purchased an item or a set of items from a shopping cart. Automatically triggered by the `_bt.trackPurchase` function.\",\n    \"5-2\": \"Indicates a user has made a change to an item or a set of items in their shopping cart.\",\n    \"5-1\": \"\",\n    \"6-0\": \"`started_membership`\",\n    \"6-1\": \"\",\n    \"6-2\": \"Indicates a new user has signed up. Automatically triggered by the `_bt.signup` function. See [Signup](doc:signup) for full details.\"\n  },\n  \"cols\": 3,\n  \"rows\": 7\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Attributes\"\n}\n[/block]\nProvided attributes will be added as metadata on the tracked event.\n\nWhile attributes can have any form, the following attribute names are reserved and may not be used:\n\n`enriched`, `event_id`, `geolocation`, `http_method`, `identified`, `identity`, `is_bot`, `is_test`, `properties`, `referer`, `status`, `url`, `user_agent`, `href`, `bsin`\n\nIf an event is tracked with any of these attribute names, the event will be rejected.\n\nThe attribute `resource_id` can be used to specify the target content that the particular action was taken on. If it is not provided, the event will be attributed to the current page.\n[block:api-header]\n{\n  \"title\": \"Examples\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// User viewed the current page\\n_bt.track('viewed');\\n\\n// User liked the current page\\n_bt.track('liked');\\n\\n// User liked resource123\\n_bt.track(\\n  'liked', \\n  {'resource_id':'resource123'}\\n);\\n\\n// User rated the current page with value 5\\n_bt.track(\\n  'liked', \\n  {'score':5}\\n);\\n\\n// User disliked the current page\\n_bt.track(\\n  'liked', \\n  {'score':-1}\\n);\\n\\n// User shared the current page with sample_user\\n_bt.track(\\n  'shared', \\n  {'target_user_id':'sample_user'}\\n);\\n\\n// User commented on the current page\\n_bt.track(\\n  'commented', \\n  {'comment_text':'This is my comment.'}\\n);\",\n      \"language\": \"javascript\",\n      \"name\": \"Sample Events\"\n    }\n  ]\n}\n[/block]","updates":[],"order":2,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"5928a0fbe2653627003e1458","createdAt":"2017-05-26T21:41:15.399Z","project":"56aff08c3a5b810d00745d99","parentDoc":null,"version":{"version":"1","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["56aff08d3a5b810d00745d9d","56aff24f3a5b810d00745da0","56aff25dbc304a0d00ace207","56aff287e0b1e40d00c53798","56aff2b260a37a0d00ed8883","56aff2b8e0b1e40d00c53799","56aff2bd5b1f01170014dc7b","56aff2c9d21e9c0d00b62993","56aff493aef9a21700da0e67","56aff4ce1486990d009c0f64","56aff4da5b1f01170014dc7d","56aff4dfe0b1e40d00c537a2","56aff4e59d32e30d0006d3e9","56aff4e91486990d009c0f65","56aff4f93a5b810d00745da2","56aff4fe9d32e30d0006d3ea","56b91c7ab1e03e0d001057c5","56c4f51aba4a540d0091b9a2","56cd09488c4a331d002c1e44","56d4ec4773dcd20b00fb8769","56e79bc515f96b2200878e54","56ec25c538ff1d2200d56cc2","56ec3a6f36bc8e0e00f190c8","56ec3e308ea7ce0e00a3d8b0","5724d8fe4255580e005938b2","5724dc842ad0bc1700122803","5776ef2a04f7500e0095dc37","57ab9f70b5e8742000e17eb9","57d7117646dcc30e007dd21f","58e6abd5b1eece19008b7d31","59288c65e2653627003e1221","5a8f4797a44f8600128e75ee","5bbf8833eb416300039a2c14","5ea811617bf4b5007328a0af"],"_id":"56aff08c3a5b810d00745d9c","project":"56aff08c3a5b810d00745d99","releaseDate":"2016-02-01T23:55:56.544Z","__v":34,"createdAt":"2016-02-01T23:55:56.544Z"},"githubsync":"","user":"566887ff8639090d00759415","__v":0,"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Zeta JavaScript Library (versions 4.x and lower)","slug":"boomtrain-javascript-sdk","order":4,"from_sync":false,"reference":false,"_id":"59288c65e2653627003e1221","createdAt":"2017-05-26T20:13:25.882Z","project":"56aff08c3a5b810d00745d99","version":"56aff08c3a5b810d00745d9c","__v":0}}

Track an Event

Tracks an event for the current user

[block:callout] { "type": "danger", "body": "This page documents a no-longer supported version of the Boomtrain JavaScript Library (versions 4.x and below). The new `p13n.js` library, documented [here](https://boomtrain.readme.io/v1/docs/p13njs-getting-started) is the currently supported library for integrating with ZetaHub.", "title": "Deprecated API Warning" } [/block] Events (also known as *activities*) are used to indicate that a user performed a particular action. These events will appear in your user's profile as recent history, and can be used to create behaviors for triggers and segmentation in the Boomtrain Marketing Engine. As well, these events act as signals for Boomtrain's personalization systems to generate insights and predictive recommendations for your campaigns. [block:code] { "codes": [ { "code": "_bt.track(event_type, [attributes], [callback]);", "language": "json" } ] } [/block] The `track` call has the following fields: [block:parameters] { "data": { "h-0": "Field", "h-2": "Description", "0-0": "`event_type`", "0-1": "String", "0-2": "The name of the event, e.g. \"viewed\", \"liked\", \"shared\". See Event Types below for more details.", "1-0": "`attributes` *optional*", "1-1": "Object", "1-2": "An object containing key:value pairs indicating attributes to be tracked as metadata in this event. See Attributes below for more information.", "2-0": "`callback` *optional*", "2-1": "Function", "2-2": "A function that is executed after this function completes and the event has been tracked. **Note:** If an event results in the user leaving the page, be sure to not navigate away until this `track` call finishes. You can ensure this by adding the page navigation call into the function specified here." }, "cols": 3, "rows": 3 } [/block] [block:api-header] { "title": "Event Types" } [/block] While you may specify any `event_type`, a few are standardized and specially handled by Boomtrain: [block:parameters] { "data": { "h-0": "Event Type", "h-2": "Description", "h-1": "Special Attributes", "0-0": "`viewed`", "0-2": "Indicates a user has viewed a page. Automatically triggered on page load when `autoTrack` is on (as it is by default). See [Getting Started](doc:getting-started-2) for full details.", "1-0": "`liked`", "2-0": "`shared`", "3-0": "`commented`", "4-0": "`purchased`", "5-0": "`updated_cart`", "1-2": "Indicates an explicit preference for the current page by the user.", "0-1": "`resource_id` - If provided, uses this value instead of the current page (default) as the viewed resource.", "1-1": "`score` - When a like is paired with a multi-point scale, provide an integer representation of the value provided. If the action indicated is a \"dislike\" or *negative* preference, use `-1`.", "2-1": "`resource_id` - If provided, uses this value instead of the current page (default) as the \"object\" of the share.\n`target_user_id` - The `user_id` of the target of the share.", "2-2": "Indicates a user has shared the current page/resource (or the one indicated by `resource_id`) with another user. Emit this once per distinct target user/resource. That is, if a user shares one article with 4 target users, trigger this event 4 times with each `target_user_id` specified.", "3-1": "`resource_id` - If provided, uses this value instead of the current page (default) as the \"object\" that was commented on.\n`comment_text` - The text of the comment.", "3-2": "Indicates a user has commented on the current page/resource (or the one indicated by `resource_id`).", "4-1": "", "4-2": "Indicates a user has purchased an item or a set of items from a shopping cart. Automatically triggered by the `_bt.trackPurchase` function.", "5-2": "Indicates a user has made a change to an item or a set of items in their shopping cart.", "5-1": "", "6-0": "`started_membership`", "6-1": "", "6-2": "Indicates a new user has signed up. Automatically triggered by the `_bt.signup` function. See [Signup](doc:signup) for full details." }, "cols": 3, "rows": 7 } [/block] [block:api-header] { "title": "Attributes" } [/block] Provided attributes will be added as metadata on the tracked event. While attributes can have any form, the following attribute names are reserved and may not be used: `enriched`, `event_id`, `geolocation`, `http_method`, `identified`, `identity`, `is_bot`, `is_test`, `properties`, `referer`, `status`, `url`, `user_agent`, `href`, `bsin` If an event is tracked with any of these attribute names, the event will be rejected. The attribute `resource_id` can be used to specify the target content that the particular action was taken on. If it is not provided, the event will be attributed to the current page. [block:api-header] { "title": "Examples" } [/block] [block:code] { "codes": [ { "code": "// User viewed the current page\n_bt.track('viewed');\n\n// User liked the current page\n_bt.track('liked');\n\n// User liked resource123\n_bt.track(\n 'liked', \n {'resource_id':'resource123'}\n);\n\n// User rated the current page with value 5\n_bt.track(\n 'liked', \n {'score':5}\n);\n\n// User disliked the current page\n_bt.track(\n 'liked', \n {'score':-1}\n);\n\n// User shared the current page with sample_user\n_bt.track(\n 'shared', \n {'target_user_id':'sample_user'}\n);\n\n// User commented on the current page\n_bt.track(\n 'commented', \n {'comment_text':'This is my comment.'}\n);", "language": "javascript", "name": "Sample Events" } ] } [/block]