audio-logger

Description

This is Ad Auris's client event logging solution. The aim is to use a common interface between our data analytic sources and our client facing applications.

We aim to track user events by registering those events onto

• Segment
  • Mixpanel
• Logging service
  • Mongo

(each tab is another edge between this package and the source)

Technologies

This is meant as an npm package we leverage np to deploy to npm

Installation & Setup

As this is meant to be an npm package you can install in your application with

npm install audio-logger

Note

once you update with np you will need to update the package.json in your other applications. This is because you will need to tell them that they require the new version instead of the old if you want your changes to take effect.

you can do this simply by executing

npm install audio-logger@x.x.x

where x.x.x is your new version number read more about version numbers here

QA Notes

When adding a new event refer to documentation for EVENT_NAME_betaAccessAttempt

When adding new attributes and want to QA that your event is being sent properly add a console log to see the payload and identify whether or not the attributes are set as you expect.

This will make more sense working inside of your client that has this package downloaded.

Interface

This section details the different interfaces that exist within this package.

Functions

init

This is the initializing function for the library, that should be called before anything else. It will help populate the event payload with neccessary information

params

• platformInfo information for platform in which events are being generated from

{ 
    platformName: 'play app',
    version: 3.0.0,
    url: window.location.href 
}

• audioPlayerRef reference to underlying audio player generally populated in react via useRef

resources:

• html-reference
• useRef

---

registerInteraction 

params

• eventType

EVENT_NAME_betaAccessAttempt

eventType's exist in the constant.js file. If you require to regsiter a new event. e.g. adding 'chrome set up success'

1. in constants.js add to eventNameMap

• key: chromeSetUpSuccess
• value: 'chrome set up success' e.g.

chromeSetUpSuccess: 'chrome set up success'

2. Create a constant EVENT_NAME_...

• where ... is the key from step 1
• have this constant equal the key as ell e.g.

const EVENT_NAME_chromeSetUpSuccess = 'chromeSetUpSuccess';

3. Export the constant from the module

you can refer to Mixpanel's lexicon to understand the semantics of each of the events.

• optionalVal: any

This can be any object, where you would like to append extra information to the event e.g.

registerInteraction(EVENT_NAME_clickLink, {
    href: 'google.com'
})

NOTE: this method allows for name rewrites there is a default parameter in the payload called uuid if you send

uuid: ''

you will overwrite the existing uuid with your new value above. This is by design to give power to the user, but with great power comes great responsibility.

---

setNarrationIdentifiers 

This function is used to change the attributes of the payload relating to the audio being played The consistency check would be ${orgIdentifier}/${articleTitleIdnetifier} would produce ttsp_id when queried on our BE

params

• orgIdentifier: string This route identifier of the organisation from which the narration was created under in our DB known as organistaions.route_identifier

• articleTitleIdentifier: string This route identifier of the article itself in our DB known as tts_package.route_identifier

• ttsp_id: number This is the id of the tts_package similarily related to the article title identifier in our DB known as tts_package.id

---

setOnPage

Let's the logger know whether the user is or is not on page

params

• isOnPage: boolean

---

sendTimeUpdate 

send a timeUpdate, to "flush" the recorded time that hasn't been recorded yet

params

---

generateRegisterInteractionFunc  

generate a function without parameters, that when called will trigger registerInteraction useful utility for supplying a callback

params

• eventName
• optionalVal

^ refer to registerInteraction to understand implicatios

---

identifyUser 

update internal state to identify the current user via localStorage only in very select use cases will this be need to be used outside of the module

params

---

initAudioPlayer 

update internal state to point to an audioPlayer reference only in very select use cases will this be need to be used outside of the module

params

• audioPlayerRef: HTMLRef reference to underlying audio player

more details in init

---

setPermUserId 

When a user logs in using firebase, enrich our user identification

params

• user: firebase.User firebase.User

---

setPageAttributes  

sets attributes relating to the current page

params

• pageAttributes: any e.g. to record the UI state of a library page

{
    library: {
        tabName: 'All'
    }
}

---

addUtmCodesToUrl  

helper function to append utm codes to a url

Valid utm codes
['source', 'medium', 'content', 'campaign'];

params

• utmObj: any

{
    source: 'ad-auris', // where traffic originated
    medium: 'play-app', // type of traffic
    campaign: 'podcast-platform-distribution', // campaign name
    content: 'listen-on-platform' // with multiple link track which link
}

• url: URL url you want to append to

resources: utm-codes

Technical Debt

This section will list some technical debt items.

local development requires deploying then installing into another package optimally instead can keep not deployed and have those packages hook into your local folder

There is a lack of testing