Marketing 101: Vanity Links
How I built a vanity link generator for the Association for Computing Machinery
Building awareness for a student organization is a challenging task. With so many events happening across a university campus, students can easily lose track of which event is being run by which student organization. In a time of growing online / hybrid engagement, building trust with your audience is a difficult but necessary requirement. When interacting with an organization’s digital content (this includes everything from zoom meetings to survey forms), the first line of marketing presence felt by an audience are links. Hyperlinks are an often forgotten aspect in digital branding but they serve as the gateway to making a strong first impression.
Most raw links that we come across are often long, ugly and unmemorable. Generic link shorteners can reduce url length and make it more convenient to share resources, but they take away from your organization’s branding in the process. When your inbox and social media is filled with hundreds of tinyurl and bitly links, just knowing which organization owns what digital resource can be tricky. These common link shorteners obfuscate the identity of the organization and make it harder for the audience to trust the reliability of the resource behind the url. It also introduces a vulnerability since any entity can generate a link like “tinyurl.com/your-org-name-event” and claim that it belongs to your organization when in fact it may be a phishing / malicious link.
By the end of this article you’ll see how our ACM chapter is able to create our own personalized vanity links like https://content.acmutd.co/medium (which by the way will take you to our medium homepage)!
Vanity Link Generator Part 1 | The Constraints
Beginning in Fall 2020, I set out to build a custom Vanity Link tool for the Association for Computing Machinery. This was the first full semester that we hosted only online events during the peak of the pandemic and our digital presence was in need of strengthening. Here were the constraints that I had to work around in designing a custom Vanity Link generator.
- Our organization owned two domains
acmutd.coandhackutd.cowhich we wanted to use in all marketing content - We had a team of approximately 60 officers and wanted this tool to only be accessible to them
- We wanted to group links under categories to help indicate what type of resource was behind the url
- We wanted to collect analytics information about how various digital resources were being accessed
Besides these functional constraints (what the system does), I also had to ensure that we were following certain non-functional requirements (how the system does it).
- Be able to operate reliably 24/7 and operate efficiently such that there’s minimal delay between creating a link and being able to use it
- Be able to securely use the tool with minimal vulnerabilities
- Ensure that officers using the tool to generate vanity links trust that it works and they have a pleasant end-to-end experience
- Maximize visibility and keep an audit trail to effectively debug issues
Vanity Link Generator Part 2 | The Basics
I’m a firm believer in the concept of “less is more” when it comes to software engineering. Writing code or developing a tool from scratch is not always the best solution. Stitching together various tools that already present can accelerate development speed, increase reliability and reduce the burden of having to maintain an extensive amount of in-house code.
The Vanity Link Generator for ACM uses a combination of various tools to accomplish its goal. These include tools that excel at data collection, data storage, link management, notifications / confirmation providers and more. Using tools that already exist also ensure that future maintainers are able to onboard quickly to understanding how the system works.
Vanity Link Generator Part 3 | The Request
We can start by looking at how an officer requests for a Vanity Link to be created. Officers start by going to fill out a Typeform that asks various questions about the vanity link they’d like to create. Typeform is an excellent service for creating forms, surveys, applications and more. It has an intuitive interface that organization members are already used to interacting with. This ensures that officers are able to trust the reliability of the resource that acts as the frontend for requesting vanity links.
An officer filling out this form needs to answer 4 basic questions. These include providing the link that they’d like to shorten & rebrand under the organization identity, the primary domain they’d like to use for the vanity link ( acmutd.co or hackutd.co ), which subdomain they’d like to use (for categorization), and finally what slash tag they want for personalizing the link to the resource.
Using Typeform makes it easy for extending upon this service should more options become available in the future. Currently, the organization manages two primary domains but this could increase as the team expands into new initiatives. By using a 3rd party tool like Typeform, it’s trival to add another choice in the dropdown without having to modify any code. Additionally, these changes can be done by anyone and not necessarily a developer.
Instead of directly using the primary domain for all links, we include requiring all links to also be associated with one of five subdomains. These help group the links under a broad category and helps the audience immediately associate what type of resource exists at the destination. For example, we typically use join.acmutd.co for zoom / google meet links, apply.acmutd.co for links to program applications, survey.acmutd.co for feedback surveys and generic forms and so on.
On occasion when hosting a special event, we have created custom subdomains just for a day to ensure that all links associated with the event look similar. For example during October 2020, for ACM’s Hacktoberfest celebrations the custom subdomain hack.acmutd.co was used for applications, links to workshops during the event & more. Internally we refer to these subdomain categories as “vanity domains”.
Once the officer has completed filling out all the questions they can just hit submit as if they were submitting any other form.
Vanity Link Generator Part 4 | The Logic
Once Typeform has received the submission it fires off a webhook call to a Firebase Cloud Function to handle processing the request. Cloud functions are a form of serverless computing. This means that all of the code can be encapsulated into a single function that executes only when a webhook request is received. During other periods of time, no resources are provisioned and there is no incurred cost. Serverless compute is an excellent cost saving option for code that runs infrequently as well as for code that carries out one small independent task. For the Vanity Link Generator, the number of requests per month are small enough that it stays completely within the Firebase free tier.
When the Cloud Function receives the request from Typeform with the raw payload, the first task it performs is to parse through the data and convert it into a simpler array of question and answer objects.
Once parsed, the Typeform data (both raw and cleaned) is immediately persisted to Cloud Firestore (a nosql database offering by Firebase). By saving this data we are able to create a data trail in the event of a failure. Viewing the database entries allows us to perform three vital steps when needing to debug.
- Verify if a successful webhook request took place by cross referencing payloads sent by Typeform and checking for the same raw payload being persisted to Cloud Firestore by the cloud function.
- Verify if invalid data was submitted. Since raw payloads are saved, we can inspect the data received to see if there were any fields or responses that caused the parsing stage to fail.
- Verify if the Cloud Function faced a different kind of error by checking the Firebase logs to see if the function was triggered but there’s no corresponding Cloud Firestore entry created at that time.
Note: In a prior implementation, Zapier was used parse and then pipe Typeform payloads directly into Cloud Firestore. Eventually, the scale of the system outpaced the Zapier free tier leading to our own custom implementation using Firebase Cloud Functions.
Vanity Link Generator Part 5 | The Vanity Link
For creating the Vanity Link we use a 3rd party service known as Rebrandly. This service manages setting up a custom domain to use for creating vanity links, handles the process of shortening the url and also collects metrics for click tracking.
Although rebrandly offers a GUI based service through their website for creating Vanity Links, the process used for ACM is completely through their API. This allows us to create a pipeline without needing to create individual accounts for each officer on the rebrandly website. The code snippet above is a simplified version of how we are able to take the payload from Typeform and use the information in it to create a Vanity Link. Additional logic is present to validate if an identical Vanity Link already exists and if so to update the destination url with a new one.
Vanity Link Generator Part 6 | The Confirmation
All steps that have been described so far in the pipeline to create a Vanity Link are asynchronous. This means that each stage kicks off as a trigger from the previous one but does not return a confirmation indicating whether it was successful or not. This means that once the officer has submitted a request to create a new Vanity Link, the frontend typeform can only confirm that the form was received but not whether the Vanity Link was successfully created.
To ensure that the officer receives confirmation about their Vanity Link being successfully created and available for use we use two different mechanisms. The first is a direct email sent to the officer that created the Vanity Link via Sendgrid.
The second is to post a confirmation message in slack in a public channel. This helps the team also be aware of which public facing links have been created and are ready for use. This transparency reduces the likelihood of duplicate Vanity Links being created for the same destination resource since all officers will be aware of any that have already been created.
It takes seconds between submitting the Typeform and receiving a confirmation that the Vanity Link is ready for use. This performance is due to series of continual optimizations in the underlying system architecture of the Vanity Link Generator. Delivering a fast and reliable service is a core goal of the project.
Vanity Link Generator Part 7 | The Security
One of the primary project requirements was to ensure that only officers are able to access this tool. To do this, instead of directly asking officers to navigate to a Typeform url, some additional security measures were taken to prevent unauthorized access. Firstly, a custom website that contains the embedded Typeform was created and deployed. This website contains additional administrative tools for use by the officer team.
To protect access to this website, we use Cloudflare Access, a service that authenticates users (via Google Workspace) and then will only allow signed in officers to access the page. This works without needing to incorporate any additional authentication logic into the website itself besides the Typeform embed because Cloudflare handles it while also resolving DNS. Once signed in, Cloudflare will insert a CF_Authorization cookie which the website can read to know who the officer filling out the form is. This cookie contains information like the officer’s name and email. These two fields are passed along with the form submission as Hidden Fields. Thus, even before filling out the form, the system is already aware of who is completing it without any manual entry required.
Once the form is submitted, we also use encryption to ensure that any information passed between Typeform and our backend Cloud Function is also secure. Payloads sent from Typeform include a Header with the body encrypted using SHA-256. This header is verified by the Cloud Function before processing the input to ensure that the webhook was indeed triggered by a Typeform submission.
Vanity Link Generator Part 8 | Closing Notes
Since its implementation in Fall 2020, the Vanity Link Generator has been the most used internal tool at ACM. With hundreds of vanity links being created year over year (over 400 for calendar year 2021), this tool has seen tremendous growth and has continued to scale with many internal improvements and optimizations. Creating a strong digital identity through these Vanity Links has ensured that the brand of the organization is present to make a great first impression with every hyperlink click.
Special thanks to Steven Nguyen, Sivam Patel, Nick Burnett, Sai Bommisetty, and Aditya Rathod for their contribution in designing, maintaining or improving the Vanity Link Generator over the past few years.
