https://github.com/lytics/pathforajs
Web personalization SDK
https://github.com/lytics/pathforajs
analytics lio-dependency lytics pathfora personalization web
Last synced: 3 months ago
JSON representation
Web personalization SDK
- Host: GitHub
- URL: https://github.com/lytics/pathforajs
- Owner: lytics
- License: mit
- Created: 2015-05-06T15:11:09.000Z (about 11 years ago)
- Default Branch: develop
- Last Pushed: 2025-12-02T19:00:23.000Z (7 months ago)
- Last Synced: 2026-01-12T00:31:23.559Z (5 months ago)
- Topics: analytics, lio-dependency, lytics, pathfora, personalization, web
- Language: JavaScript
- Homepage: https://www.lytics.com/
- Size: 9.91 MB
- Stars: 2
- Watchers: 5
- Forks: 0
- Open Issues: 44
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
[](https://github.com/lytics/pathforajs/blob/develop/LICENSE.md)
[](https://travis-ci.org/lytics/pathforajs)
[](https://david-dm.org/lytics/pathforajs)
[](https://david-dm.org/lytics/pathforajs?type=dev)
[](https://codecov.io/gh/lytics/pathforajs)
# Pathfora JS
Pathfora JS is a lightweight SDK for displaying personalized modules on your website, it integrates with your [Lytics](http://www.getlytics.com/) account to track user actions, and conditionally display modules based on your users' audience membership. For more info and full configuration examples check out the [full documentation](https://lytics.github.io/pathforadocs/).
## Modules
There are 4 types of modules and 5 layouts currently supported.
**Modules can be of the following types:**
- **Message** - Module with a simple text message.
- **Form** - Module with a form to capture user information, can contain fields for `name`, `email`, `title` and `message`.
- **Subscription** - Module with a single input field, `email`.
**Modules are displayed in one of following layouts:**
- **Modal** - A large size module with an overlay behind it - meant to cover a substantial area of the browser window, so that it demands attention from the user.
- **Slideout** - A medium module which slides from either side into the window.
- **Bar** - A thin module which appears at the top or bottom of the browser window.
- **Button** - A small module which only allows for a short call to action and a single click action.
- **Inline** - A module which can be inserted into an existing div on a page.
- **Gate** - Module which gates the page behind it - essentailly the same as the Modal layout without the "x" button, so the user must interact with the gate content to dismiss it.
## General Usage
1. Add [Lytics tracking tag](https://docs.lytics.com/docs/lytics-javascript-tag) to your website, and import pathfora.js file.
```html
```
2. Set up your module configuration, a simple example is provided below. See the [documentation](http://lytics.github.io/pathforadocs/) for a full list of settings and examples.
```javascript
// example: show a bar module with a button leading to a new products page
var module = new pathfora.Message({
id: 'bar-valued-customers',
layout: 'bar',
msg: 'Thanks for being a valued customer, please check out our new products.',
cancelShow: false,
okMessage: 'View Now',
confirmAction: {
name: 'view now',
callback: function () {
window.location.pathname = '/new-products';
},
},
});
pathfora.initializeWidgets([module]);
```
## Communication
**`slack`** - There’s a [slack channel](https://join.slack.com/t/pathforajs/shared_invite/enQtMjcyNDEzMDY4NzIxLTI5ZDIyMDI2NGEzNjU4NDE3MTgyOWQ2YzM5MzhjZjVmZDljMDE3NmU5MDFmYmExNTA5ODlhZmE4NmM2ZmE3MTI). Feel free to join and collaborate!
## Contributing to Pathfora
[See contribution notes](CONTRIBUTION.md)
## Development
Pathfora uses [yarn](https://yarnpkg.com) for package management, [rollup](https://github.com/rollup/rollup) as a module bundler, and [Gulp](https://github.com/gulpjs/gulp) to manage build tasks.
Install Dependencies:
Note: Node v12 is not compatiable with the current set of dependencies. See https://github.com/gulpjs/gulp/issues/2324
```sh
$ yarn global add gulp-cli
$ yarn install
```
Gulp tasks:
- **`gulp build`** - minify `LESS` files. Bundle, lint and uglify `js` modules in the `src/rollup` directory, and place output files in `dist` directory.
- **`gulp`** - runs the `build` tasks above and watches for any changes in the `src` directory, files are served on `localhost` port `8080`.
- **`gulp docs`** - [see below](#documentation).
- **`gulp lint`** - lint all the `js` source files with the rules defined in [.eslintrc](https://github.com/lytics/pathforajs/blob/develop/.eslintrc).
- **`gulp local`** - reads some config params from an optional local file, `.env.json` and builds and watches as with the default gulp task. This can allow you to test CSS changes locally (by default `dist/pathfora.min.js` loads the most recently deployed CSS file) or override the Lytics API URL.
Example `.env.json` file, (using local CSS):
```json
{
"APIURL": "https://c.lytics.io",
"CSSURL": "http://localhost:8080/dist/pathfora.min.css"
}
```
Useful scripts:
- **`yarn test`** - builds and activates Karma test runner on PhantomJS.
- **`yarn run clean`** - removes files from the `./dist` folder for a clean build.
- **`yarn run build:prod`** - sets `NODE_ENV` to `production` and builds minified files in `./dist` folder.
- **`yarn run prod`** - run tests, clean and rebuild the `/dist` folder. This is built on top of the `gulp build`
command. Important to know that this sets the `NODE_ENV` to `production`, removing instabul instrumentation for code coverage. Currently, this is the default command used for our Travis CI.
- **`yarn run local`** - run the gulp server to test things locally.
### Documentation
Documentation for the most recent release is available [here](http://lytics.github.io/pathforadocs/).
You can also view and add to the docs by running the `gulp docs` task. Our docs are powered by [mkdocs](http://www.mkdocs.org/) which you must install before attempting to run the docs.
```sh
$ pip install mkdocs
$ gulp docs
```
Documentation will be served on `localhost` port `8000` while running this task.
The source code for all the examples provided in the documentation can be found in `docs/docs/examples/src`. Preview images for the examples are stored in `docs/docs/examples/images`.
The docs task will walk through every `.js` file in the examples source directory and compile it as a working html example in `docs/docs/examples/preview` using a handlebars template. These js files also get used as the source code to populate the `
` elements within the docs.
This allows us to keep our source code in one place. Changing a js file in the examples source folder will change the code snippet in the docs and update the example .html file.
### Testing
Pathfora uses [Jasmine](https://github.com/jasmine/jasmine) as a test framework, and [Karma](https://github.com/karma-runner/karma/) to run tests. Before running tests, or commiting changes be sure to run `gulp build` instead of `gulp local`, or tests may fail due to mismatching URLs.
Running tests:
```sh
$ yarn run test
```
## License
[MIT](LICENSE.md)
Copyright (c) 2017, 2016, 2015 Lytics