palzintrack
TypeScript icon, indicating that this package has built-in type declarations

1.0.8 • Public • Published
Palzin Track

PalzinTrack

Get notifications and track your project events.

NPM Version Documentation

Web Analytics

Palzin Track Web SDK

Installation

You can use Palzin Track Web SDK by adding the following script tag to your HTML file to install the web library. Please don't forget to update the TOKEN and PROJECT ID values with your own values.

<script 
    async="true" 
    src="https://palzin.live/rel/v1.0/trck/pt.js" 
    data-project-id="<YOUR_PROJECT_ID>" 
    data-api-key="<YOUR_PUBLIC_API_TOKEN>" 
    data-auto-track="true"
    data-cache="true"
    data-domains="mywebsite.com,mywebsite2.com"
></script>

Palzin Track provides several properties that allow you to configure its behavior.

data-project-id and data-api-key (required)

By default, Palzin Track will send data to wherever the script is located. You can override this to send data to another project with its appropriate API TOKEN. You will need to change the value of data-project-id and data-api-key.

Usage:

<script
    defer
    src="https://palzin.live/rel/v1.0/trck/pt.js"
    data-project-id="<YOUR_PROJECT_ID>" 
    data-api-key="<YOUR_PUBLIC_API_TOKEN>"   
></script>

data-auto-track

By default, Palzin Track tracks all pageviews and events for you automatically. You can disable this behavior and track events yourself using the Web SDK Functions.

Usage:

<script
    defer
    src="https://palzin.live/rel/v1.0/trck/pt.js"
    data-project-id="<YOUR_PROJECT_ID>" 
    data-api-key="<YOUR_PUBLIC_API_TOKEN>"   
    data-auto-track="false"
></script>

data-cache

If you get a lot of pageviews from the same user, for example in a forum website, you can cache some data to improve the performance of the tracking script.

Note: This will use session storage so you may need to inform your users._

Usage:

<script
  defer
    src="https://palzin.live/rel/v1.0/trck/pt.js"
    data-project-id="<YOUR_PROJECT_ID>" 
    data-api-key="<YOUR_PUBLIC_API_TOKEN>"
    data-cache="false"
></script>

data-domains

If you want the tracker to only run on specific domains, you can add them to your tracker script. This is a comma delimited list of domain names. Helps if you are working in a staging/development environment.

Usage:

<script
  defer
    src="https://palzin.live/rel/v1.0/trck/pt.js"
    data-project-id="<YOUR_PROJECT_ID>" 
    data-api-key="<YOUR_PUBLIC_API_TOKEN>"
    data-domains="mywebsite.com,mywebsite2.com"
></script>

Google Tag Manager

Google Tag Manager will strip the attributes from the tracker, so you can bypass this by using the format below.

<script>
  (function () {
    var el = document.createElement('script');
    el.setAttribute('src', 'https://palzin.live/rel/v1.0/trck/pt.js');
    el.setAttribute('data-project-id', '<YOUR_PROJECT_ID>');
    el.setAttribute('data-api-key', '<YOUR_PUBLIC_API_TOKEN>');
    document.body.appendChild(el);
  })();
</script>

Note: Please ensure that your token is set to "Public" and its roles are limited to the project you're tracking.

Tracker Functions

The Palzin Track Web SDK tracker exposes a function that you can call on your website if you want more control over your tracking. By default everything is automatically collected, but you can disable this using data-auto-track="false" and sending the data yourself.

See Web SDK Configuration.

Functions

pt.track([payload]);

pt.track(event_name, [event_data]);

Pageviews

Tracks a page view.

pt.track();

By default the tracker automatically collects the following properties:

  • project: Project ID (required)
  • hostname: Hostname of server
  • query: URL Query
  • 'userId': User Id
  • vp_size: View Port size
  • language: Browser language
  • referrer: Page referrer
  • screen: Screen dimensions (eg. 1920x1080)
  • title: Page title
  • url: Page url
  • utm_source: UTM Source
  • ua: User Agent
  • tags: Tags in Array
  • path: URL path

If you wish to send your own custom payload, pass in an object to the function:

pt.track({ project: 'e676fas-dsf43u9-afda8-773e9f2', url: '/home', title: 'Home page' });

The above will only send the properties website, url and title. If you want to include existing properties, pass in a function:

pt.track(props => ({ ...props, url: '/home', title: 'Home page' }));

Events

Tracks an event with a given name.

pt.track('signup-button');

Event Data

Tracks an event with dynamic data.

pt.track('signup-button', { name: 'product analytics newsletter', id: 123 });

When tracking events, the default properties are included in the payload. This is equivalent to running:

pt.track(props => ({
  ...props,
  name: 'signup-button',
  data: {
    name: 'product analytics newsletter',
    id: 123,
  },
}));

Tracking Events Using HTML

Tracking custom events is as simple as defining a data attribute on any element. For example, let's track when a user upgrades their plan.

<button
  data-pt-event="Upgraded Plan"
  data-pt-event-channel="billing"
  
>
  Upgrade to Pro
</button>

Custom Properties using HTML

You may add custom properties to your events by defining a data attribute on any element. Remember, the only required property is data-event, everything else is optional.

<button
  data-pt-event="Upgraded Plan"
  data-pt-event-userid="user-123"     // optional (optional when set using window.ls)
  data-pt-event-channel="billing"      // optional (defaults to "events")
  data-pt-event-icon="💰"      // optional
  data-pt-event-tag-plan="Pro"         // optional
  data-pt-event-tag-period="Monthly"   // optional
  data-pt-event-tag-price="9.99"       // optional
>
  Upgrade to Pro
</button>

Event Data Limits

Event Data can work with any JSON data. There are a few rules in place to maintain performance.

  • Numbers have a max precision of 4.
  • Strings have a max length of 256.
  • Arrays are converted to a String, with the same max length of 256.
  • Objects have a max of 50 properties. Arrays are considered 1 property.

Note: Make sure you don't cache the provided script else the new released feature may get affected.

Package Sidebar

Install

npm i palzintrack

Homepage

palzin.live

Weekly Downloads

4

Version

1.0.8

License

MIT

Unpacked Size

62.2 kB

Total Files

12

Last publish

Collaborators

  • palzin