feat: sync doc with bayanplus-js

0ss · 0ss · commit 43f04ac797a5 · 2023-02-22T23:45:05.000+03:00
diff --git a/docs/getting-started/add-bayanplus-to-your-website.md b/docs/getting-started/add-bayanplus-to-your-website.md
@@ -3,30 +3,41 @@ title: Add Bayanplus to your website
 sidebar_position: 1
 ---
 
-
 To add Bayanplus to your website, you will need to add the below this line of code to the `<head></head>` tag in you HTML file
 
-The tracking script has `pid` parameter which has your project id and you must add it so the script can work. You can find it in the setting page of your project, it will look something like this, or can copy and paste the code from the setting page in your project directly
+The tracking script has `data-pid` parameter which has your project id and you must add it so the script can work. You can find it in the setting page of your project, it will look something like this, or can copy and paste the code from the setting page in your project directly
 
 If you are using Javascript library/framework like React **we recommond checking** [this](../libraries/javascript.md)
+
 ```html
-<script defer pid="Your Project Id" src="https://cdn.bayanplus.co/bp.js"></script>
+<script
+  defer
+  data-pid="Your Project Id"
+  src="https://cdn.bayanplus.co/bp.js"
+></script>
 ```
- 
-:::info 
+
+:::info
 
 Bayanplus will only accept tracking request that has project id parameter `pid` and are coming from the project exact domain and it is subdomains
 
 :::
 
-## Tracking from localhost
-Bayanplus does not accept data coming from developemt enviroment, so if you are in development mode using something like `localhost:3000` it wouldn't work. However, you can bypass that by passing `data-track-localhost`
+## Development mode
+
+If you are in development mode using something like `localhost:3000` you can use the attribute `data-dev` which will not record events
+
 ```html
-<script defer data-track-localhost pid="Your Project Id" src="https://cdn.bayanplus.co/bp.js"></script>
+<script
+  defer
+  data-dev
+  data-pid="Your Project Id"
+  src="https://cdn.bayanplus.co/bp.js"
+></script>
 ```
 
 ## Automatic tracking
 
-All page views are **automatically tracked**, you don't need any extra configuration whatsoever, we send a new request anytime the URL changes. We track traditional websites that has many HTML pages and SPAs like React, Angular and Vue. 
+All page views are **automatically tracked**, you don't need any extra configuration whatsoever, we send a new request anytime the URL changes. We track traditional websites that has many HTML pages and SPAs like React, Angular and Vue.
 
 If you need custom event tracking like tracking button click or signup then definitely check out [custom event tracking](../how-to/track-custom-events.md)
diff --git a/docs/how-to/exclude-pages-from-being-tracked.md b/docs/how-to/exclude-pages-from-being-tracked.md
@@ -1,6 +1,6 @@
 ---
 title: Exclude pages from being tracked
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 By default Bayanplus does what is called [Automatic Tracking](/getting-started/add-bayanplus-to-your-website#automatic-tracking). But what if there are some pages in your website that you don't want them to be tracked and included in your dashboard? you can do that with the help of our script, the script will recognize the pages you want to be excluded and will just simple ignore them from being tracked
@@ -10,53 +10,60 @@ Here's how you can do that with help of our script
 ## Use `data-exclude` to exclude pages
 
 Once you have added the embedded [Bayanplus script](/getting-started/add-bayanplus-to-your-website) all you need to is to `data-exclude` attribute to the script with the pages you want to exclude.
-For example let's say we want to exclude `/login` page from being tracked. 
+For example let's say we want to exclude `/login` page from being tracked.
 
 Here's how it will look like:
+
 ```html
-<script defer data-exclude="/login" pid="Your Project Id" src="https://cdn.bayanplus.co/bp.js"></script>
+<script
+  defer
+  data-exclude="/login"
+  data-pid="Your Project Id"
+  src="https://cdn.bayanplus.co/bp.js"
+></script>
 ```
+
 You can see the attribute `data-exclude="/login"` was added to the origin script which will help up to exclude `/login` page and now it **will not** be count int your Bayanplus dashboard
 
 :::caution
 You want to exclude a pages, just make sure to include '/' in the beginning.
-Do this `data-exclude="/login"` 
-and not this `data-exclude="login"` 
+Do this `data-exclude="/login"`
+and not this `data-exclude="login"`
 :::
 
 ## Exclude multiple pages
 
 You can also exclude as many pages as you just make sure they are **coma-seperated**.
-For example let's say we want to exclude `/login`, `/register` and `/hello` from being tracked. 
+For example let's say we want to exclude `/login`, `/register` and `/hello` from being tracked.
 
 Just add them together and seperate them with a coma:
 
 ```html
-<script defer data-exclude="/login, /register, /hello" pid="Your Project Id" src="https://cdn.bayanplus.co/bp.js"></script>
+<script
+  defer
+  data-exclude="/login, /register, /hello"
+  data-pid="Your Project Id"
+  src="https://cdn.bayanplus.co/bp.js"
+></script>
 ```
 
-## Advanced pages excluding 
- 
+## Advanced pages excluding
+
 Bayanplus script will recognize the below format for excluding pages
+
 ```
 data-exclude="/login, /admin/*, /blog-*, /*/admin, /*/stat/*"
 ```
-Any page listed in this format will not be tracked. The asterisk `*` in simple words means **anything**.
-
-Example 
-- `/admin/*` is `/admin/<anything>`, will exclude any path that comes after `/admin/` like 
-`/admin/profile` or `/admin/password` 
-
-- `/blog-*` is `/blog-<anything>`, anything comes in format of `/blog-*` like `/blog-1` or `/blog-2323` will be excluded.
-
-- `*/admin/` is  `<anything>/admin `, will exclude any path comes in format of `*/admin` like `/users/admin`
-
-- `*/stat/*` is  `<anything>/stat/<anything> `, will exclude any path comes in format of `*/stat/*` like `/dashboard/stat/main`
-
-
 
+Any page listed in this format will not be tracked. The asterisk `*` in simple words means **anything**.
 
+Example
 
+- `/admin/*` is `/admin/<anything>`, will exclude any path that comes after `/admin/` like
+  `/admin/profile` or `/admin/password`
 
+- `/blog-*` is `/blog-<anything>`, anything comes in format of `/blog-*` like `/blog-1` or `/blog-2323` will be excluded.
 
+- `*/admin/` is `<anything>/admin `, will exclude any path comes in format of `*/admin` like `/users/admin`
 
+- `*/stat/*` is `<anything>/stat/<anything> `, will exclude any path comes in format of `*/stat/*` like `/dashboard/stat/main`
diff --git a/docs/how-to/track-custom-events.md b/docs/how-to/track-custom-events.md
@@ -8,22 +8,24 @@ Events are useful and powerful features, allowing you to get a better insights a
 Bayanplus automatically groups all the events you visitors has done and show it on the dashboard. You can see from the picture the the name for all event, in our case we have `downloads`, `sign up`. The count tell you how many this event or actions has been done by your visitors, and the conversion is the perecentage of completion out of all the visitors. So for example if you had 1000 visitors last 24 hours, and only 100 from those have sign up, then the conversion rate would be 10%
 
 ## Sending an event
-You can start sending custom events with no extra configurations, all you need is to make sure the script is installed, [click if you haven't](/getting-started/add-bayanplus-to-your-website). 
+
+You can start sending custom events with no extra configurations, all you need is to make sure the script is installed, [click if you haven't](/getting-started/add-bayanplus-to-your-website).
 
 You can start using two options:
 
 ### Using Javascript
 
-The Bayanplus script you havve installed already exposes Bayanplus object globally. You can access it in `window.bayanplus` or just `bayanplus` is enough. If you are using a javascript framework or build tool we recommand using our offical npm library [bayanplus-js](track-custom-events.md)
+The Bayanplus script you have installed already exposes Bayanplus object globally. You can access it in `window.bayanplus` or just `bayanplus` is enough. If you are using a javascript framework or build tool we recommand using our offical npm library [bayanplus-js](https://www.npmjs.com/package/bayanplus-js)
+
+To track an event, simple call `bayanplus()` function in your code. and pass the name of the event you want, Sign up for example
 
-To track an event, simple call `bayanplus()` function in your code.  and pass the name of the event you want, Sign up for example
 ```javascript
-window.bayanplus("Sign up")
+window.bayanplus.event("Sign up");
 // or
-bayanplus("Sign up")
+bayanplus.event("Sign up");
 ```
-For the above example, the `Sign up` event will be recorded to current visitor session. The `bayanplus` function takes an argument which is the name of the event, we recommand giving **short and straightforward** events name
 
+For the above example, the `Sign up` event will be recorded to current visitor session. The `event` function takes an argument which is the name of the event, we recommand giving **short and straightforward** events name
 
 ### Using HTML attributes
 
@@ -34,30 +36,20 @@ You need to specfiy the name of the event and whenever this element is clicked B
 ```html
 <button data-bayanplus-event="Sign up">Sign up to our website!</button>
 ```
+
 #### HTML Forms
 
 Also it is easy to track form submission just in same way using above example
-just append `data-bayanplus-event` to the form element. 
+just append `data-bayanplus-event` to the form element.
 If the user submits the form the an event will be triggered, in below example it is called `Subscribe to newsletter`
 
+:::info
+Bayanplus will not send or record any custom data like passwords our email in below case, only the event name, so do not worry about this
+:::
+
 ```html
 <form data-bayanplus-event="Subscribe to newsletter">
   <input name="email" type="email" />
   <button type="submit">Subscribe</button>
 </form>
 ```
-:::info
-Bayanplus will not send or record any custom data like passwords our email in above case, only the event name, so do not worry about this
-:::
-
-## Important note
-Please make sure you **do not include** any personally identifiable information (PII) in sending event to bayanplus. This might include `Phone number`, `Email`, `IP address` 
-
-For example, the below example is **highly discouraged and bad a example**
-```javascript
-//  user ip address is considered personall data
-bayanplus(`IP ${getUserIPaddress()}`)
-
-// some cookies are senstive
-bayanplus(`session ${getCookieByName("session_id")}`)
-```
diff --git a/docs/how-to/track-subdomains.md b/docs/how-to/track-subdomains.md
@@ -1,24 +1,24 @@
 ---
 title: Track subdomains
-sidebar_position: 2
+sidebar_position: 3
 ---
 
-
-
-It is common for a business also to have multiple subdomains along (eg. `docs.bayanplus.co`, `cdn.bayanplus.co`) so If your website has subdomains you want to track it also, you can do so with two options. Either create new project for this subdomain, or re-use the same script across the subdomains. 
+It is common for a business also to have multiple subdomains along (eg. `docs.bayanplus.co`, `cdn.bayanplus.co`) so If your website has subdomains you want to track it also, you can do so with two options. Either create new project for this subdomain, or re-use the same script across the subdomains.
 
 :::info
 When Bayanplus recieves new tracking request, it checks the `host` and see if it matches the domain of project or it is subdomain, if so it accepts it otherwise distract it.
 :::
 
-## Tracking subdomains options 
+## Tracking subdomains options
+
 In simple words, you can do either of these things:
+
 - **Multiple subdomains, multiple dashboards**:
-For each subdomains you have (eg. `docs.bayanplus.co`, `cdn.bayanplus.co`) you can create a project for each one with isolated dashboard, each project (subdomain) will have it is own script.
-Sessions will be isolated for each subdomains (eg. if someone visited `cdn.bayanplus.co` and then went to `docs.bayanplus.co` it will be counted as one two seperate sessions)
-- **Multiple subdomains, one dashboard**, 
-Create just one project that for your domains and all your subdomains you want track, and place the same script on all the subdomains. Sessions will be tracked across the subdomains (eg. if someone visited `cdn.bayanplus.co` and then went to `docs.bayanplus.co` it will be counted as one session). 
+  For each subdomains you have (eg. `docs.bayanplus.co`, `cdn.bayanplus.co`) you can create a project for each one with isolated dashboard, each project (subdomain) will have it is own script.
+  Sessions will be isolated for each subdomains (eg. if someone visited `cdn.bayanplus.co` and then went to `docs.bayanplus.co` it will be counted as one two seperate sessions)
+- **Multiple subdomains, one dashboard**,
+  Create just one project that for your domains and all your subdomains you want track, and place the same script on all the subdomains. Sessions will be tracked across the subdomains (eg. if someone visited `cdn.bayanplus.co` and then went to `docs.bayanplus.co` it will be counted as one session).
 
-For example, If someone visited `bayanplus.co` after few minutes went to `docs.bayanplus.co` to read the documenation. Since both domains use the same script (the 2nd option). Bayanplus will automatically group and merge the tracking data made across those domains in one dashboard for you. 
+For example, If someone visited `bayanplus.co` after few minutes went to `docs.bayanplus.co` to read the documenation. Since both domains use the same script (the 2nd option). Bayanplus will automatically group and merge the tracking data made across those domains in one dashboard for you.
 
-**It is more convenient and easier to use the 2nd option** which you can simply just put the script on one or more domains (eg. `bayanplus.co`, `docs.bayanplus.co`) and Bayanplus will merge the analytics data then for you.
+**It is more convenient and easier to use the 2nd option** which you can simply just put the script on one or more domains (eg. `bayanplus.co`, `docs.bayanplus.co`) and Bayanplus will merge the analytics data then for you.
diff --git a/docs/how-to/track-users.md b/docs/how-to/track-users.md
@@ -0,0 +1,40 @@
+---
+title: Track users
+sidebar_position: 2
+---
+
+Creating user profiles allows you to store custom data about your users, such as their name, email, or ID, in addition to the data that Bayanplus already stores, you can view them in Users page. A profile is a user with attached custom data.
+
+To create a basic profile, you can use the `bayanplus.user.set()` function and provide the desired data, like this:
+
+```typescript
+bayanplus.user.set({
+  id: 123456,
+  name: "Salah",
+  email: "Salah@gmail.com",
+});
+```
+
+## Authenticate your users
+
+If you want to authenticate your users, you can set a unique ID using the same function, this is useful
+if you have multiple apps or devices and you want track the user across them.
+Bayanplus will recognised **id** as unique identifier.
+It will convert anonymous session into a **Profile**
+
+```typescript
+bayanplus.user.set({ id: 123456 });
+```
+
+## Write custom data
+
+When you create a user profile, you can attach custom data to the user, such as their plan type or their preferred color scheme. You can set this data using the `bayanplus.user.set()` function:
+
+```typescript
+bayanplus.user.set({ plan: "free", isDarkMode: true });
+bayanplus.user.set({ name: "Salah", email: "salah@bayanplus.co" });
+```
+
+You can call this function at any time to store data for the user. By default, data is appended to any existing data for the user. If you provide a field that already exists, it will be overwritten.
+
+To retrieve the data you have set for the user, you can use the `bayanplus.user.get()` function.
diff --git a/docs/intergrations/nextjs.md b/docs/intergrations/nextjs.md
@@ -12,40 +12,25 @@ yarn add bayanplus-js
 ```
 
 ## Usage
+
 After you install it, you can start using it by calling `bayanplus.init()` and pass the `projectId` as a parameter to so bayanplus can recognize you project. After that **Bayanplus will track page views automatically** [see this](../getting-started/add-bayanplus-to-your-website.md#automatic-tracking)
-```javascript
-// /pages/_app.js
-import bayanplus from 'bayanplus-js'
-useEffect(() => {
-      bayanplus.init({
-        projectId: "xxxx",
-      })
-  }, [])
-return  <Component {...pageProps} />
-```
-## Tracking with localhost
-Bayanplus does not accept data coming from developemt enviroment, so if you are in development mode using something like `localhost:3000` it wouldn't work. However, you can bypass that by passing `trackLocalhost: true`
 
 ```javascript
 // /pages/_app.js
-import bayanplus from 'bayanplus-js'
-function MyApp({ Component, pageProps }) {
-
+import bayanplus from "bayanplus-js";
 useEffect(() => {
-      bayanplus.init({
-        projectId: "xxxx",
-        trackLocalhost: true,
-      })
-  }, [])
-  
-return  <Component {...pageProps} />
-}
-export default MyApp;
+  bayanplus.init({
+    projectId: "xxxx",
+    isDev: false, //  if you data set to `true` so your data won't be tracked in case you are in development mode
+  });
+}, []);
+return <Component {...pageProps} />;
 ```
 
 ## Sending custom events
+
 ```javascript
-import bayanplus from 'bayanplus-js'
+import bayanplus from "bayanplus-js";
 import { useState } from "react";
 
 export function SignupForm(props) {
@@ -54,7 +39,7 @@ export function SignupForm(props) {
   const handleSubmit = (e) => {
     e.preventDefault();
     // Record custom event on submit
-    bayanplus("Signup to newsletter");
+    bayanplus.event("Signup to newsletter");
   };
 
   return (
@@ -71,4 +56,4 @@ export function SignupForm(props) {
     </form>
   );
 }
-```
+```
diff --git a/docs/intergrations/reactjs.md b/docs/intergrations/reactjs.md
@@ -3,8 +3,7 @@ title: ReactJS
 sidebar_position: 2
 ---
 
-
-To integrate Bayanplus to your React application, **you have two options**, either embed the Bayanplus script in you html file [see here](../getting-started/add-bayanplus-to-your-website.md) 
+To integrate Bayanplus to your React application, **you have two options**, either embed the Bayanplus script in you html file [see here](../getting-started/add-bayanplus-to-your-website.md)
 
 Or to install the offical npm library by running
 
@@ -15,24 +14,21 @@ yarn add bayanplus-js
 ```
 
 ## Usage
+
 After you install it, you can start using it by calling `bayanplus.init()` and pass the `projectId` as a parameter to so bayanplus can recognize you project. After that **Bayanplus will track page views automatically** [see this](../getting-started/add-bayanplus-to-your-website.md#automatic-tracking)
+
 ```javascript
-import bayanplus from 'bayanplus-js'
+import bayanplus from "bayanplus-js";
 
 // first and most important initiliaze the app with the project id
 // you can find the project id on https://bayanplus.co
 // you only need to do this once
 bayanplus.init({
-    projectId: 'xxxxx'
-})
+  projectId: "xxxxx",
+  isDev: false,
+});
 
-// if you are in development mode
-bayanplus.init({
-    projectId: 'xxxxx',
-    trackLocalhost:true
-})
 // now you can track any event you want like
 // you can track as many events you want on any file as long as you initiliazed the app
-bayanplus.track('Buy Book')
-
-```
+bayanplus.event("Buy Book");
+```
diff --git a/docs/welcome.md b/docs/welcome.md
diff --git a/docusaurus.config.js b/docusaurus.config.js
