npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@phantomstudios/ft-lib

v0.4.1-rc1

Published

A collection of Javascript UI & tracking utils for FT sites

Downloads

135

Readme

ft-lib

NPM version Actions Status PR Welcome

A collection of Javascript utils for shareable UI and tracking functionality across Phantom FT sites

Introduction

currently implemented:

  • FTTracking - Consolidated Origami and GA/GTM event tracking for page and interaction events.
  • consentMonitor - polls the FT consent cookies set by the approved FT Origami cookie banner to enable/disable the FT Permutive ad tracking
  • permutiveVideoUtils - formatted permutive video progress events
  • reactPlayerTracking - Video tracking for FT sites implementing videos with react-player
  • ytIframeEventHandler - Video tracking handler for FT sites with embedded Youtube Iframe API videos.

Installation

Install this package with npm.

npm i @phantomstudios/ft-lib

Usage

FTTracking

Shared Origami and GA/GTM tracking implementation that can be used across all Phantom FT sites. Tracking meta data is provided by a config object when first initiated and on subsequent route changes (only required for SPA/NextJS sites). By default, the implementation will automatically handle FT tracking via data-gadl and data-o-event HTML attributes. The tracker instance should be added to the global window namespace if custom events are required. Note: By default the FTTracker instance will load the consentMonitor poller, so sites do not need to implement this separately.

The constructor requires the config JSON object (TODO - schema) and optionally accepts an options object:

Default options

  scrollTrackerSelector: "#o_tracker_scroll",  //top level DOM element selector for scroll tracking
  isCustomGTMEvent: true, //selects between GTM and UA(GTAG) event formats - TODO - handle automatically by detecting loaded GTM/UA?
  disableAppFormatTransform: false, //by default the config.app variable is formatted, ie: "app": "home-page" -> "app": "Home_page" - set to true to disable this formatting

Config/Event format validator

The site config JSON object passed in the constructor and all events handled by FTTracker are validated with Yup for a basic format check. This includes both the automatic data-o-event, data-gadl generated events and manually fired events with FTTracker.oEvent and FTTracker.gaEvent. A console error is thrown if validation fails. The validation rules can be found in /src/utils/yupValidator.ts

Typical usage:

import { FTTracking } from '@phantomstudios/ft-lib'

//For Wagtail sites, get server-rendered o-tracking-data
const config = JSON.parse(document.getElementById('o-tracking-data').textContent)
window.FTTracker = new FTTracking(config, { scrollTrackerSelector: '#content' })
.
.
//if an event needs to be fired that can't be added using the preferred data-gadl and data-o-event attributes (i.e. custom players or form submits):
window.FTTracker.oEvent({category: "audio", action: "progress", duration: duration, progress: {`${progress}%`}})
window.FTTracker.gaEvent(`Audio`, {`${progress}% progress`}, <AUDIO or PAGE TITLE>)

consentMonitor

Adds an FT consent cookie poller to enable/disable Permutive consent (only useful if 'consentRequired' is set as an option in the site's Permutive script - see here There are optional constructor args for the hostname (defaults to window.location.hostname) and the dev environment host matches (defaults to ["localhost", "phq", "vercel.app"]) which are used to determine development environments in order to generate an FT banner event listener ((see here for a list of banner DOM events) to set session-level cookies for development environments

import { consentMonitor } from "@phantomstudios/ft-lib";

new consentMonitor("FT.staging.testsite.com". ["localhost", "phq", "staging"]);

permutiveVideoUtils

emitPermutiveProgressEvents - used within a video player's progress event handler to fire Permutive video progress events at [0, 25, 50, 75, 100] percent progress. Optional 3rd arg to pass a window.interval instance to be cleared once progress is complete.

import { permutiveVideoUtils } from "@phantomstudios/ft-lib";

const permutivevideoTracker = new permutiveVideoUtils("<FT-CAMPAIGN>","<VIDEO-TITLE>","<VIDEO-ID/URL>")  //Data will be site implementation specific

player.on("progress", () => {   //event will be video player site implementation specific
   permutivevideoTracker.emitPermutiveProgressEvent(<DURATION>, <CURRENTTIME>, <OPTIONAL-WINDOW-INTERVAL>)
});

reactPlayerTracking

Exports video event handlers that broadcast the required GA, oTracking and Permutive events.

The constructor takes the parent site's FTTracking instance (typically set up as window.FTTracker) and video and site meta data (as required for the tracking data).

Typical implementation:

import { reactPlayerTracking } from "@phantomstudios/ft-lib";

const [videoTracker] = useState(
   new reactPlayerTracking(window.FTTracker, <VIDEO-TITLE>, <VIDEO-URL>),
)

<ReactPlayer
   onDuration={videoTracker.setDuration}
   onEnded={videoTracker.trackEnded}
   onPause={videoTracker.trackPause}
   onPlay={videoTracker.trackPlay}
   onProgress={videoTracker.trackProgress}
>

ytIframeTracking

Exports a Youtube iframe event handler for sites using the Youtube Iframe API that broadcasts the required GA, oTracking and Permutive events. The Youtube iFrame can be either generated in the site's JS or template rendered.

The constructor takes the parent site's FTTracking instance (typically set up as window.FTTracker).

NOTE: For Typescript usage as below, the @types/youtube NPM package should be added to the parent project and the YT namespace added to tsconfig.json with the "types": ["youtube"] compiler option.

Typical implementation:

import { ytIframeTracking } from '@phantomstudios/ft-lib';

const VIDEO_IFRAME_ID = 'video-iframe';

export class YoutubeIframeLoader {
  videoTracker: ytIframeTracking;
  player?: YT.Player;

  constructor() {
   this.videoTracker = new ytIframeTracking(window.FTTracker);

   window.onYouTubeIframeAPIReady =
    (event: YT.PlayerEvent) => {
      this.player = new YT.Player(VIDEO_IFRAME_ID, {
        events: {
          'onStateChange': (event) => this.onPlayerStateChange(event)
        }
      });
    };

   onPlayerStateChange(event: YT.PlayerEvent) {
    this.videoTracker.ytIframeEventHandler(event);
   }
  }
}