Support for SPA apps

Last week I had an interested support request by Jack, who is running an Astro based site that basically is an SPA (Single Page App) app. Astro uses the "View Transition API" (whatever that is 😅) — however that caused some issues with the Tinylytics embed script.

So behold, I made a special version of the script that handles SPA's much better. It's not perfect as it requires a bit of manual tweaking, but fear not.

One thing to remember about the embed script is, is that it's dynamic — which means depending on what you want, for example kudos, webring and so on, it will give you a slightly different version. That's to keep the size super minimal for just what you need!

New SPA option

Now you can request the script in SPA friendly format which will give you some extra goodies! To get started, all you have to do is add the spa parameter to the script tag. For example:

<script src="https://tinylytics.app/embed/YOUR-SITE-ID.js?spa&kudos"></script>

In the above example you can see both the spa parameter and also kudos — that's because, in this case, I am interest in loading the SPA version of the script (hence this post) and also load kudos on my page.

The script works as normal, but now we have some extra tools available to us. It also changes the behaviour on how certain things are loaded.

With the usual SPA's it'll just transition to another page without reloading the script, or sometimes it duplicates the script — so here we had problems with the original script where it would load twice and then get confused and do the wrong thing, or not load at all.

With the SPA version of the script, we now give you access to some of the script in the window object. That means you can listen for the script load event to handle local state.

To recap: When Tinylytics loads the script, it will attach itself to the window so it's available to you in window.tinylytics. On the first load of the script — basically the first time the site loads — it will set itself up as normal, send a hit and also look for any extras, like Kudos.

In addition, there is a tinylytics:did-load event you can listen to within your code — that will be triggered the first time the script loads.

Tinylytics Window Object

With this, you have several options that you can use for your integration. I've kept this super minimal for now, and more than happy to expand if you so need.

Here is what you've got available to you after the script has successfully loaded:

window.tinylytics.loaded # should be true
window.tinylytics.triggerUpdate # this triggers an update of the script

window.tinylytics.loaded — This will be available to you once the script loaded, so you can check if it did in fact load. It always returns true if it's attached to the window.

window.tinylytics.triggerUpdate — This option is available once tinylytics is attached to the window object. Use this to basically trigger an update — meaning it will re-trigger the script to send a hit, and also look for anything on the page that needs setting up, like Kudos and other. Just call window.tinylytics.triggerUpdate() and Bob's your uncle.

Tinylytics on-load Event

Once the script is initially loaded, you'll get the following event sent your way: tinylytics:did-load. You can listen for this, like the following:

document.addEventListener('tinylytics:did-load', () => {
  // Optional: Use this to listen if the script successfully loaded
  // and handle any internal state if you want to.
  updateMyState()
})

Do what you need with this as you see fit. You probably don't need it, but it's good to have I reckon.

Example code

Taking the example of Jack's Astro site, here is us triggering an update after the page has "swapped" to a new page.

document.addEventListener('astro:after-swap', () => {
  // Use the after-swap to trigger a tinylytics update.
  // Once the tinylytics script is loaded, it'll be available
  // with window.tinylytics. This exposes another function that
  // triggers an update (sends a hit, sets up kudos buttons etc).
  // NOTE: On initial load of the embed script, it will trigger this
  // automatically. You only need to call window.tinylytics.triggerUpdate()
  // after you have navigated (because the embed script is already loaded).
  if (window.tinylytics){
    window.tinylytics.triggerUpdate()
  }
});

That works pretty well and keeps everyone happy.

Thank you Jack for letting me play with your code and getting this out to everyone ✌️❤️ 

As always, I offer great support so if there is anything you need, let me know!