How to manage custom dimensions across multiple GA properties with nodejs admin API - basics
Tamas Tumbasz · May 8, 2023 · 7 min read
Introduction
Have you ever completed a task and wondered, is this really the best way to do it? — is this it? For me that moment came when I was setting up custom dimensions and metrics for GA4. The number of custom properties and the number of times I needed to do the same thing over and over again with the UI provided in GA interface dragged me down and made me wonder if there was a better way to handle this task.
In this case the answer was yes, there is a better way! In this post I will share what can be done—or at least what I find to be efficient and reasonable.
If you need to create, edit, or delete a custom property in more than one place, you will need to perform the same action multiple times. This can be acceptable for one GA property, but in case you have more properties, let’s say 9, you will need to do the same thing 9 times, once for each GA property.
Issues with this workflow:
- It is error / typo prone
- Even in the best case, the time complexity is not linear but leans towards exponential
- It requires bookkeeping level of documentation, else it can be a tedious task to provide basic information about the state
The solution presented here mitigates these issues as follows:
- It ensures a single source of truth for the action (same data will be used for create / edit actions, no space for typos, missed properties)
- A script will perform the tasks instead of you
In short, there is no magic; it’s just calling an API with the right parameters—then you are good to go. Even if it can be banalised as “just calling an API”, here you can find a digested solution that can work out of the box.
Now let’s get to the fun part where we make this happen!
Implementation
[My assumptions are that you know some javascript, you have used git, and you know how to run pre-made scripts from package.json.]
First thing you need is a service account and grant that account appropriate rights in GA properties you want to manage.
How to create a service account?
- Go to your GCP ( Google Cloud Platform )
- Navigate to IAM & Admin
- Select Service Accounts
- Click on create service account, no additional permission are needed here
- Select newly created account
- Click on keys
- Click on add key -> JSON
- That key will be download -> we are going to use it later -> after it is used, delete it / keep it safe
If you haven’t used the service account, please consult the official documentation.
You should also grant the appropriate access rights for the GA properties for which you want to run these scripts (the appropriate level would be editor).
Now that that’s out of the way, we can start our little project / exercise. There will be arepo attached to this article, so you can try it out later.
The first step is to ensure that the script can communicate with GA. To do that, fill out the .env file with the values from the key JSON that you have downloaded after you created the service account. Please read the Notes sections, just to be on the safe side.
Where to find things and how they work
Creation of custom dimensions
In the const folder you can find a file named ga_properties.ts and in there you can add your GA property ids. You can find the property id in the url analytics.google.com/analytics/web/#/p123456789/reports/…, where 123456789 is the property id and you can use it fill out the array of objects. You can also find it in the admin panel. The important thing is that the IDs are correct.
Note: we are going to use these IDs to create custom properties.
In the variables folder you can find a file named customDimensions.ts and in there you can add custom dimensions you want to have on the properties you have defined above. Keep in mind the number of available custom dimensions in your GA properties. If you define more custom dimensions that you have available slots, this script will run successfully until you reach the limit, any custom custom dimension that exceed the limit will not be created.
Now that we know which GA properties we want to add custom dimensions to, and which custom dimension should be added, it’s time for some excitement!
Execute the createCustomDimensions command and observe your custom dimensions being created.
In the console you should be able to see that the custom dimensions have been created. And if something went wrong, there should be error logs. For verification you can check in GA interface if the dimensions were created.
Removal of custom dimensions
In the variables folder you can find a file named removeDimensions.ts, fill out the array with the property IDs. As for creation, in the root of the project, run this command -> pnpm deleteCustomDimensions. The console output should let you know that the custom dimensions have been deleted, but you should also verify in GA that the action was performed as expected.
Now you might wonder, where do I find the property ids? In the variables folder you can find a file named findDimensions.ts, replace the value with the parameter name you are seeking. Same as for creation, in the root of the project, run this command -> pnpm findCustomDimensions. This will write the values into data/foundDimensions.txt, you can use that value as property ids for removal.
Modification of custom dimensions
This one is trickier than the previous three actions that we described, and it’s bit limited. Fields that you can modify are display name, descriptions and disallowAdsPersonalization, what means that in case you want to rename a parameter name, you would essentially need to delete the parameters that you want to rename and create new parameters. If you followed me this far, I’m confident you can puzzle out how this action works based on given example in the repo.
Ideas for extending this exercise
- create a script that will list out all custom dimensions, like all custom dimensions in each property, and/or a list of properties that are unique or missing from the other properties
- create a change log - just a function that will log the date and change made to the custom dimensions to a file
- make it a console application
- make it a fullstack app / desktop app
- make scripts for managing custom metrics - this should be easy as the approach is more or less same
Notes
Note regarding .env file and service account JSON
For the sake of demonstration we have used a dummy service account JSON and a fake .env file. THIS IS VERY RISKY AND YOU SHOULD NOT DO THIS! The service account key json should not be in the repo and the .env variables should not be committed. If you ignore this warning, you might receive an unpleasant call from your higher-ups (and unlike people like Mark Zuckerberg, you will have to take the consequences as well as the responsibility).
Note regarding usage of these little scripts
Please be reasonable when using these scripts. If you don’t understand how they work, or if you haven’t discussed them ahead of time with your coworkers, please don’t use them on production GA properties. It unlikely you will do damage using them, but it’s not impossible (like winning the lottery). If something breaks because of code you found online, it’s on you.
Notes regarding the project setup
As this is my exercise, I picked the tools and conventions I wanted to try out. Feel free to adjust, replace, or rewrite it. In the end, it’s just a setup and there is no right way to do it. And never forget, you can not make everyone happy, but you can make everyone mad.
Useful resources
nodejs analytics admin github repo service account documentation
Closing words
With a bit of fiddling you can make your daily tasks more enjoyable—this little exercise is a proof of that. This demo is made to speed up a part of process of migration. I hope you find it enjoyable to use. Please don’t be shy in modifying, extending, or breaking it.
Also also, if this post get some traction I would be open to expanding it, as there are other cool things that this API can do, as well as other APIs that can play with GA.
As always, if you have questions, feel free to ask.
