Skip to content
Permalink
Browse files

Initial commit

  • Loading branch information...
embee8 committed Nov 7, 2018
0 parents commit 25e470659395f370bfb14b899014030f5d64d621
Showing with 546 additions and 0 deletions.
  1. +14 −0 .eslintrc
  2. +3 −0 .gitignore
  3. +3 −0 CHANGELOG.md
  4. +2 −0 CODE_OF_CONDUCT.md
  5. +36 −0 CONTRIBUTING.md
  6. +21 −0 LICENSE
  7. +100 −0 README.md
  8. +25 −0 events/acquisition.js
  9. +31 −0 events/activation.js
  10. +23 −0 events/ar-camera.js
  11. +24 −0 events/conversion.js
  12. +31 −0 events/customer-care.js
  13. +33 −0 events/index.js
  14. +36 −0 events/predefined.js
  15. +22 −0 events/retention.js
  16. +21 −0 events/sharing.js
  17. +88 −0 index.js
  18. +33 −0 package.json
@@ -0,0 +1,14 @@
{
"parserOptions": {
"ecmaVersion": 2017
},
"env": {
"es6": true
},
"rules": {
"camelcase": [2, {"properties": "always"}],
"indent": ["error", 2],
"semi": ["error", "always"],
"quotes": ["error", "double"]
}
}
@@ -0,0 +1,3 @@
node_modules
package-lock.json
.vscode
@@ -0,0 +1,3 @@
1.0.0 (November 7, 2018)

* Initial version
@@ -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.
@@ -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.
21 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.
100 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.
@@ -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;
@@ -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;
@@ -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;
@@ -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;
@@ -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;
@@ -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,
};
@@ -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;

0 comments on commit 25e4706

Please sign in to comment.
You can’t perform that action at this time.