Integration with Pure(Vanilla) Javascript

In this section we will explain how can you integrate your website with embedding Metricalp script to your website. All other integration libraries use this method under the hood.

First of first, you need yourt tid (a.k.a Tracker ID). You can get it from Tracker Settings / Embed & Share screen.

After you get your tid, you are ready to embed metricalp script to your website. You need place the below code snippet to top of every page. Please do not forget to replace YOUR_TID with your tid.

<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" defer></script>

That's all. Metricalp automatically will start to collect events from your website just after this one line. How awesome is that right? 🫡

Now lets deep dive into details. The above script has `defer` attribute, which it means the script will not block page load, but the script execution will happen before than any other script execution on the page which comes after this script. But still, if you want to load script asynchronously, you can remove `defer` attribute and change it with `async` attribute. But this time while script will be loaded async way, it can be problem if you want to fire an immediate event just after page load, because maybe script load is not completed before than you triggeer event. To solve this and make all process smoother, we can add more one line just above our script:

<script>window.metricalp = window.metricalp || {queue: [], event: function(e){this.queue.push(e)}}</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

Now we replaced defer with async and we added one more line just above our script line. We guarantee that every event will be pushed independently load time of our main script. Because now we are collecting our events in a queue until our script loads, then it fires all events in thr queue. So, you can fire events immediately after a page load. We recommend this second code snippet in general (we are using this in our integration libraries) because it is more performant, safe and lightweight for page load.

While providing data-tid attribute we provided another data attribute which data-allow-localhost="true" because as default Metricalp never collects events from localhost (127.0.0.1) to save from your usage quota. But if you are integrating first time, you can allow localhost events for testing purposes. After you finish your integration, you can remove this attribute before publishing your website to production. Detailed info can be found in allow localhost & exclude me docs

There are a few more options to customize Metricalp script behaviours, you can find all in API reference.

Defaultly, Metricalp automatically starts to collecting screen_view events (it can be disabled with data-disable-auto-route-catch option please check API reference for details). But if you want to fire an event manually (screen_view or any custom event), you can use window.metricalp.event function or custom data attributes. You will learn more about this in Custom Event & Props. If you are firing custom events, your script should be loaded before than you trigger event. Generally, that is the case in both two code snippets above. But, in first scenario if you are firing event before than call of defer script, it can be a miss. While this is very very rare/edge case, you can use second code snippet to be sure 100%.

Also, sometimes you may want to attach some custom props to some (or all) events automatically. You can set this with second approach and define that will automatically attached props in sharedCustomProps object like:

<script>
      window.metricalp = window.metricalp || {
          queue: [],
          sharedCustomProps: {
            _global: { custom_prop1: "Test1" },
            screen_view: {
              logged_in: 'not_logged_in',
              custom_prop2: "Test2",
            }
          },
          event: function(e){this.queue.push(e)}
      }
</script>
<script src="https://cdn.metricalp.com/event/metricalp.js" data-allow-localhost="true" data-tid="YOUR_TID" async></script>

_global is special key for attaching some props to all events. Keep in mind that, if you are attaching a custom prop via alias, then that alias should be defined for target events in Tracker Settings otherwise it will be ignored for that event. You can use custom_prop1 like syntax for any event always. Again, you can get more detailed info about sharedCustomProps in Custom Event & Props section. Also, if you are using React library to integrate Metricalp with React / NextJS, you can check React and NextJS docs to learn how can you set sharedCustomProps in your React / NextJS app.