Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/the-bugging/react-use-hotjar
Adds Hotjar capabilities as custom hooks such as init, identify and stateChange
https://github.com/the-bugging/react-use-hotjar
custom-hooks hooks hotjar identifying-users react statechange typescript
Last synced: 1 day ago
JSON representation
Adds Hotjar capabilities as custom hooks such as init, identify and stateChange
- Host: GitHub
- URL: https://github.com/the-bugging/react-use-hotjar
- Owner: the-bugging
- License: mit
- Created: 2020-08-11T00:02:54.000Z (over 4 years ago)
- Default Branch: develop
- Last Pushed: 2024-01-16T03:55:01.000Z (12 months ago)
- Last Synced: 2025-01-11T09:47:13.251Z (4 days ago)
- Topics: custom-hooks, hooks, hotjar, identifying-users, react, statechange, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/react-use-hotjar
- Size: 3.43 MB
- Stars: 32
- Watchers: 2
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# react-use-hotjar
> Adds [Hotjar](https://www.hotjar.com/) capabilities as custom hooks to your project
[](https://www.npmjs.com/package/react-use-hotjar)
---
| Statements | Branches | Functions | Lines |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|  |  |  |  |
## Table of Contents
- [Install](#install)
- [Usage](#usage)
- [Examples](#examples)
- [Documentation](#documentation)
- [Contributors](#contributors)
- [License](#license)
---
## Install
```bash
npm install --save react-use-hotjar
```
---
## Usage
- Initializing Hotjar (use it at the very top of your application)
```tsx
import * as React from 'react';
import useHotjar from 'react-use-hotjar';
const myCustomLogger = console.info;
const HotjarReadyApp = () => {
const { initHotjar } = useHotjar();
React.useEffect(() => {
initHotjar(1234567, 6, false, myCustomLogger);
}, [initHotjar]);
return ;
};
```
- Identifying Users (Use it wherever user's information is available. Send and object respecting [Identify API's rules](https://help.hotjar.com/hc/en-us/articles/360033640653-Identify-API-Reference#user-attribute-values))
```tsx
import * as React from 'react';
import useHotjar from 'react-use-hotjar';
const myCustomLogger = console.log;
const MyCustomComponent = () => {
const { identifyHotjar } = useHotjar();
const handleUserInfo = (userInfo) => {
const { id, ...restUserInfo } = userInfo;
identifyHotjar(id, restUserInfo, myCustomLogger);
};
};
```
---
## Examples
- You may find a running [example](./example) in this project which are served at [Github Pages](https://olavoparno.github.io/react-use-hotjar).
- Also, a running codesandbox [codesandbox](https://codesandbox.io/s/react-use-hotjar-dkcjp)
---
## Documentation
`useHotjar()` returns:
- An object with the following keys:
| key | description | arguments | example |
| -------------- | -------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| readyState | States if Hotjar is ready | N/A | N/A |
| initHotjar | Initialize method | (hotjarId: number, hotjarVersion: number, hotjarDebug?: boolean, loggerCallback?: console[method]) | (1933331, 6, false, console.info) |
| identifyHotjar | User identify API method | (userId: string, userInfo: object, loggerCallback?: console[method]) | ('abcde-12345-12345', {name:"Olli",surname:"Parno",address:"Streets of Tomorrow"}, console.log) |
| stateChange | Relative path state change | (relativePath: string, loggerCallback?: console[method]) | ('route/logged-route/user?registered=true') |
| tagRecording | Tag a recording | (tags: string[], loggerCallback?: console[method]) | (['tag1', 'tag2']) |
- initHotjar()
1. `hotjarId`: Your Hotjar application ID ex.: 1933331
2. `hotjarVersion`: Hotjar's current version ex.: 6
3. `hotjarDebug`: Optional Debug Mode to see hotjar logs in console ex.: true
4. `logCallback`: Optional callback for logging whether Hotjar is ready or not
```tsx
initHotjar: (
hotjarId: string,
hotjarVersion: string,
hotjarDebug?: boolean,
logCallback?: () => void
) => boolean;
```
- identifyHotjar()
1. `userId`: Unique user's identification as string
2. `userInfo`: User info of key-value pairs (note this must not be so long and deep according to [docs](https://help.hotjar.com/hc/en-us/articles/360033640653-Identify-API-Reference)) (Please note: **The Identify API is only available to Business plan customers.**)
3. `logCallback`: Optional callback for logging whether Hotjar identified user or not
```tsx
identifyHotjar: (userId: string, userInfo: object, logCallback?: () => void) =>
boolean;
```
- stateChange()
1. `relativePath`: A change in a route specially for SPAs usage. [stateChange docs](https://help.hotjar.com/hc/en-us/articles/360034378534)
2. `logCallback`: Optional callback for logging whether Hotjar stateChange was called or not
```tsx
stateChange: (relativePath: string, logCallback?: () => void) => boolean;
```
- tagRecording()
1. `tags`: List of strings to associate with a recording that can be used for filtering
2. `logCallback`: Optional callback for logging whether Hotjar tagRecording was called or not
```tsx
tagRecording: (tags: string[], logCallback?: () => void) => boolean;
```
---
## Contributors
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Olavo Parno
🤔 💻 ⚠️
Gianpietro Lavado
📖
Ivan Kleshnin
💻 🤔
Ajay Varghese
💻 🤔
honicole
🔧 💻 🤔 📖
Georg Bakken Idland
📖 🤔
Jason Papakostas
🐛
Luighi Viton-Zorrilla
🐛 🚧
Quentin Luc
💻
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
---
## License
react-use-hotjar is [MIT licensed](./LICENSE).
---
This hook is created using [create-react-hook](https://github.com/hermanya/create-react-hook).