To show you how tags work, we’ll start with adding a simple custom code tag. It’s a tag that can contain any code and do anything you tell it to do. In our example, we’ll use a script that displays a popup on a page:
<script>
alert('Hello, world!');
</script>We’ll experiment with this tag but won’t publish it. So no worries, this popup won’t go live on your site or app.
To add a custom code tag, follow these steps:
- Go to Menu > Tag Manager.
- Navigate to Tags.
- Click Add a tag.
- Choose the following tag type: Custom code (async) and click Next.
Note: Tags belong to two categories:
- Async tags don’t interfere with loading page content. The browser can load all tags at the same time, and it doesn’t wait for a certain tag to load completely before moving to the next one. Async tags load faster than sync tags and are better for collecting data. Most of the tags in Piwik PRO are async tags.
- Sync tags (deprecated) load before the page content loads. They also wait for the tag content to load before moving on to the next content. Sync tags are often used to run A/B tests.
To run sync tags, you need to install an additional container on your site or app. Read more
Synchronous containers and tags will be discontinued by January, 2025. We recommend removing them and adjusting your setups accordingly. Read more
- Name the tag. For example,
(popup) Hello, world!. - In a code editor, we can add any JavaScript code we want. So here we’ll add our popup code:
<script> alert('Hello, world!'); </script>
Tip: In Piwik PRO, built-in tags have the main tag setup at the top. The setup varies from tag to tag. But they also have some additional setup that is the same in each tag, like consent settings, flight dates and attached triggers.
- In Advanced tag settings, we’ve got a few optional settings:
- Consent type: To comply with privacy laws, set the consent type you want to use to fire this tag. This setting works only when you use a consent form on your site. The form is turned on or off under Administration > Sites & apps > Ask visitors for consent. Read more
- Respect opt-out and DNT: If turned on, this tag won’t fire for visitors who set Do-Not-Track in their browsers or for visitors who opt out of tracking using our opt-out form.
- Don’t fire in debug mode: If turned on, this tag won’t fire in debug mode but will still fire on your site or app.
- Enable document.write: If turned on, you can use the document.write method in this tag.
- In Flight dates, you can set the day and time to run this tag.
- In Tag triggers, you need to add a new or existing trigger. We’ll add a new page-scroll trigger.
- Click Add a trigger.
- Choose the following type: Page scroll.
- Name the trigger. Example:
25% scroll mark. - Click Next.
- Set the scroll mark. We’ll set it as 25%.
- Click Save.
- The trigger is now attached to this tag.
- Click Save.
- Done! Your tag is now saved as a draft. It’s not yet published on your site or app.
Tip: Every time you create or change a new tag, trigger or variable, they won’t appear immediately on your site or app but will be saved as a draft.
Always debug!
In the web developer’s world, everything needs to be tested out before going live. The same rule applies to tags. You want to make sure that your code works smoothly and has no bugs. For that purpose, Tag Manager has a safe and controlled environment called debug mode. In this mode, you can see how the tags will work when deployed.
We repeat it like a mantra: “Always debug.” It prevents you from firing a wrong, broken or buggy tag that can cause turmoil on your site or in the collected data. It is a shield that safeguards your online experiments. Now let’s see how to use it.
To use debug mode, follow these steps:
- Go to Menu > Tag Manager.
- In the top-right corner, click Debug.
- Your site or app will open in a new tab with debug mode running.
- Scroll down the page and see if the popup is displayed.
Tip: Most tags won’t display a popup on a site or app so you’ll have to check tag details in debug mode to see if everything is working properly.
- Look for your tag on the tag list and see if it fired.
- Click on your tag to see tag details.
- If you see that your tag hasn’t fired, check the attached triggers for this tag. Usually, the problem lies in triggers that aren’t set up correctly.
- Click Events log to see events that were recorded on your site while testing it.
- Click stg.scroll on the event list. It’s a page-scroll event. Here you can see which tags were fired for this event.
- Now would be the moment to go back to Tag Manager and click Publish. We’ll do it to show you further steps, but you can leave it alone for now. Keep in mind that this tag displays a popup on a site, and you might not want to do that yet.
Tip: When you click Publish, Tag Manager will publish all changes in tags, triggers and variables. Make sure that everything is set up correctly before you make changes live.
- All done! Our first tag has just been published on our site.
Look at the changelog
After publishing your tag, you can also look at the changelog, which will show you all the changes made on your site or app.
To view the changelog, follow these steps:
- Go to Menu > Tag Manager.
- Navigate to Changelog.
- Click on the last snapshot.
- On our snapshot, we can see the tag we’ve published:
(popup) Welcome, world!.
- Click on the added tag to see change details.
- If you’re making lots of changes and want to keep track of them, you can look at the list of all unpublished changes in the changelog. Click Unpublished changes on the left.
Tip: Read more about the changelog in Tag Manager.
Let’s wrap up. In this chapter, we showed you how to add, debug and publish a tag. We also peeked into the changelog, which helps you keep track of changes. You already know the basics, and now we can move on to the world of tags.