Initial commit

.eslintrc

@@ -0,0 +1,14 @@
+{
+	"parserOptions": {
+    "ecmaVersion": 2017
+  },
+  "env": {
+    "es6": true
+  },
+	"rules": {
+    "camelcase": [2, {"properties": "always"}],
+    "indent": ["error", 2],
+		"semi": ["error", "always"],
+		"quotes": ["error", "double"]
+	}
+}

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+package-lock.json
+.vscode

CHANGELOG.md

@@ -0,0 +1,3 @@
+1.0.0 (November 7, 2018)
+
+* Initial version

CODE_OF_CONDUCT.md

@@ -0,0 +1,2 @@
+# Code of Conduct
+Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please [read the full text](https://code.facebook.com/codeofconduct) so that you can understand what actions will and will not be tolerated.

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to Facebook Analytics for Messenger
+We want to make contributing to this project as easy and transparent as possible.
+
+## Pull Requests
+We actively welcome your pull requests.
+
+1. Fork the repo and create your branch from `master`.
+2. If you've added code that should be tested, add tests.
+3. If you've changed APIs, update the documentation.
+4. Ensure the test suite passes.
+5. Make sure your code lints.
+6. If you haven't already, complete the Contributor License Agreement ("CLA").
+
+## Contributor License Agreement ("CLA")
+In order to accept your pull request, we need you to submit a CLA. You only need
+to do this once to work on any of Facebook's open source projects.
+
+Complete your CLA here: <https://code.facebook.com/cla>
+
+## Issues
+We use GitHub issues to track public bugs. Please ensure your description is
+clear and has sufficient instructions to be able to reproduce the issue.
+
+Facebook has a [bounty program](https://www.facebook.com/whitehat/) for the safe
+disclosure of security bugs. In those cases, please go through the process
+outlined on that page and do not file a public issue.
+
+## Coding Style  
+* 2 spaces for indentation rather than tabs
+* 80 character line length
+* Hyphens to separate words in file and folder names
+* Camel case for variables and functions
+
+## License
+By contributing to Facebook Analytics for Messenger, you agree that your contributions will be licensed
+under the LICENSE file in the root directory of this source tree.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Facebook, Inc. and its affiliates.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,100 @@
+# Facebook Analytics for Messenger
+
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/facebook/react/blob/master/LICENSE)
+
+The `messenger-analytics` module offers a simple interface to Facebook Analytics (FBA) for Messenger bots. It provides a thin integration layer as well as a collection of commonly used bot events.
+
+The included event namespace is not meant to be exhaustive but aims to provide basic guidance around the following questions:
+
+* Which events should my bot log?
+* Which events are important for my industry / vertical / use case?
+* How can I optimize my bot and increase customer satisfaction over time?
+
+Facebook Analytics (FBA) is a people-first analytics tool for an omni-channel world. It can be used as a standalone logging solution for your Messenger bot or in addition to other analytics software. FBA is closely integrated with the Facebook ecosystem, including Ads Manager and the Facebook Pixel. This allows you to get a complete view of the full marketing funnel.
+
+## Background
+The Facebook Messenger platform automatically logs certain events for your bot, for example "message sent" and "message received". These events are logged on the app-level and can be visualized in [Facebook Analytics (FBA)](https://analytics.facebook.com). In addition to these automatic events, FBA also supports the logging of custom events which enable you to visualize user journeys and track the performance metrics of your choice.
+
+In other words, custom events help you improve your service over time based on real interactions. Furthermore, it helps you to assess the effectiveness and [ROI](https://en.wikipedia.org/wiki/Return_on_investment) of your Messenger bot compared to other channels.
+
+## Installing the module
+```
+npm install messenger-analytics --save
+```
+
+## Importing the module
+```js
+const FBA = require("messenger-analytics");
+```
+
+## Creating an event logger
+Create a logger using the app and page ID associated with your bot.
+```js
+const logger = new FBA.Logger({
+    appID: YOUR_APP_ID,
+    pageID: YOUR_PAGE_ID,
+});
+```
+
+## Logging events
+The simplest form of logging an event is to provide an event name and the user identifier (PSID). You can either use an event name defined in this module or choose an arbitrary name.
+
+**Note: Whenever possible and applicable, use the so called *predefined app events* in `FBA.EventNames.Predefined`. They are utilized across the Facebook ecosystem and can be used for attribution and campaign optimization in Ads Manager. Given the significance of these events for other products, it is advisable to treat them as first choice.**
+
+```js
+// Using a predefined event name (required if you want to report on a specific metric in Ads Manager)
+logger.logEvent(
+  FBA.EventNames.Predefined.Purchased,
+  "USER_PSID",
+).then(() => {
+  console.log("Event successfully logged to FBA.");
+}).catch((err) => {
+  console.error(err);
+});
+
+// Using a custom event name
+logger.logEvent(
+  "subscribed_sports_news",
+  "USER_PSID",
+).then(() => {
+  console.log("Event successfully logged to FBA.");
+}).catch((err) => {
+  console.error(err);
+});
+```
+
+You may also attach additional parameters to an event. These parameters can be used for filtering, segmentation, and campaign reporting. Predefined events have specific parameter definitions which need to be followed if you want to log purchases and see the purchase value and currency in Ads Manager, as an example. The parameter definitions can be found in the [App Events API event structure](https://developers.facebook.com/docs/marketing-api/app-event-api#event_structure). On top of these standard parameters, you may also add additional custom parameters to the event. Parameters for custom events don't have to follow any naming convention.
+
+```js
+// Purchase event with 3 standard FB parameters and 1 custom parameter
+logger.logEvent(
+  FBA.EventNames.Predefined.Purchased,
+  "USER_PSID",
+  {
+    _valueToSum: 87.90, // standard parameter, defaults to 1
+    fb_num_items: 3, // standard parameter
+    fb_currency: "EUR", // standard parameter
+    custom_var: "hello_world", // custom parameter
+  }
+).then(() => {
+  console.log("Event successfully logged to FBA.");
+}).catch((err) => {
+  console.error(err);
+});
+
+// Net Promoter Score (NPS) event
+logger.logEvent(
+  FBA.EventNames.CustomerCare.NpsResponse,
+  "USER_PSID",
+  {
+    rating: 9,
+  })
+).then(() => {
+  console.log("Event successfully logged to FBA.");
+}).catch((err) => {
+  console.error(err);
+});
+```
+
+## License
+Facebook Analytics for Messenger is MIT licensed, as found in the LICENSE file.

events/acquisition.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+"use strict";
+
+/*
+ * How do people discover your bot?
+ *
+ * Related docs:
+ * https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_referrals
+ * https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_optins
+ */
+
+const Acquisition = {
+  EnteredThroughReferral: "entered_through_referral",
+  NewConversation: "new_conversation",
+  ResurrectedConversation: "resurrected_conversation",
+  OptIn: "opt_in",
+};
+
+module.exports = Acquisition;

events/activation.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+"use strict";
+
+/*
+ * How do people use your bot?
+ *
+ * Related docs:
+ * https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messages
+ * https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_postbacks
+ * https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-deliveries
+ * https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/message-reads
+ * https://developers.facebook.com/docs/messenger-platform/reference/webhook-events/messaging_account_linking
+ */
+
+const Activation = {
+  AccountLinked: "account_linked",
+  MessageRead: "message_read",
+  MessageReceived: "message_received",
+  MessageSent: "message_sent",
+  PostbackReceived: "postback_received",
+  Subscribed: "subscribed",
+  Unsubscribed: "unsubscribed",
+};
+
+module.exports = Activation;

events/ar-camera.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+"use strict";
+
+/*
+ * AR for Messenger Platform
+ *
+ * Related docs:
+ * https://developers.facebook.com/docs/messenger-platform/camera-effects
+ */
+
+const AR = {
+  CameraDismissed: "camera_dismissed",
+  CameraNewUser: "camera_new_user",
+  CameraExistingUser: "camera_existing_user",
+};
+
+module.exports = AR;

events/conversion.js

@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+"use strict";
+
+/*
+ * How do people transact in the bot?
+ *
+ * Related docs:
+ * https://developers.facebook.com/docs/messenger-platform/payments#custom_webview
+ */
+
+const Conversion = {
+  FilteredSearch: "filtered_search",
+  BookmarkedItem: "bookmarked_item",
+  ViewedItem: "viewed_item",
+  PurchasedItem: "purchased_item",
+};
+
+module.exports = Conversion;

events/customer-care.js

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+"use strict";
+
+/*
+ * How are customers offered support and resolution?
+ *
+ * Related docs:
+ * https://developers.facebook.com/docs/messenger-platform/handover-protocol
+ * https://developers.facebook.com/docs/messenger-platform/identity/customer-matching
+ */
+
+const CustomerCare = {
+  SupportCaseOpened: "support_case_opened",
+  SupportCaseClosed: "support_case_closed",
+  SupportCaseResolved: "support_case_resolved",
+  HandedOverToAgent: "handed_over_to_agent",
+  HandedOverToBot: "handed_over_to_bot",
+  PromptedForDeflection: "prompted_for_deflection",
+  InitiatedDeflection: "initiated_deflection",
+  CompletedDeflection: "completed_deflection",
+  NpsResponse: "nps_response",
+  CsatResponse: "csat_response",
+};
+
+module.exports = CustomerCare;

events/index.js

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+"use strict";
+
+/**
+ * Commonly used events for Messenger bots
+ * @module messenger-analytics/events
+ */
+
+const Acquisition = require("./acquisition"),
+  Activation = require("./activation"),
+  AR = require("./ar-camera"),
+  Conversion = require("./conversion"),
+  CustomerCare = require("./customer-care"),
+  Predefined = require("./predefined"),
+  Retention = require("./retention"),
+  Sharing = require("./sharing");
+
+module.exports = {
+  Acquisition,
+  Activation,
+  AR,
+  Conversion,
+  CustomerCare,
+  Predefined,
+  Retention,
+  Sharing,
+};

events/predefined.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+"use strict";
+
+/*
+ * Whenever possible and applicable, use these predefined app events.
+ * They are utilized across the FB ecosystem and can be used
+ * for attribution and campaign optimization in Ads Manager.
+ * 
+ * Related docs:
+ * https://developers.facebook.com/docs/app-events/getting-started-app-events-web
+ */
+
+const Predefined = {
+  AchievedLevel: "fb_mobile_level_achieved",
+  AddedPaymentInfo: "fb_mobile_add_payment_info",
+  AddedToCart: "fb_mobile_add_to_cart",
+  AddedToWhishlist: "fb_mobile_add_to_wishlist",
+  CompletedTutorial: "fb_mobile_tutorial_completion",
+  CompletedRegistration: "fb_mobile_complete_registration",
+  InitiatedCheckout: "fb_mobile_initiated_checkout",
+  Purchased: "fb_mobile_purchase",
+  Rated: "fb_mobile_rate",
+  Searched: "fb_mobile_search",
+  SpentCredit: "fb_mobile_spent_credits",
+  UnlockedAchievement: "fb_mobile_achievement_unlocked",
+  ViewedContent: "fb_mobile_content_view",
+  ViewedPage: "fb_page_view",
+};
+
+module.exports = Predefined;