Tracking Twitter/X Ads in a Rails Application with Ahoy Matey

tracking.md

Tracking Twitter/X Ads in a Rails Application with Ahoy Matey

This guide will walk you through setting up tracking for your Twitter/X ads using Ahoy Matey in a Rails application.

Step-by-Step Guide

Step 1: Add UTM Parameters to Your Ad Links

What are UTM parameters?

UTM parameters are tags added to a URL that help track the performance of campaigns. Common UTM parameters include:

• utm_source: Identifies the source of the traffic (e.g., Twitter, Facebook).
• utm_campaign: Identifies the specific campaign (e.g., a particular ad campaign).
• twclid: A unique identifier provided by Twitter to track clicks.

Choosing UTM Parameter Values:

You can choose the values for utm_source and utm_campaign based on your needs. These values can be anything you like, but they should be consistent with what you expect in your controller for tracking purposes.

Ad Text Example:

Revolutionize your social media strategy with Echosight! Showcase your Twitter/X analytics, compare with the community, and enhance your credibility with our public analytics page. Sign up now to see how you rank among top users and tell a compelling story with your data. [Sign up now](https://app.echosight.io/?utm_source=twitter&utm_campaign=social_media_ad&twclid=12345)

URL Example:

https://app.echosight.io/?utm_source=twitter&utm_campaign=social_media_ad&twclid=12345

Explanation:

• utm_source=twitter: This indicates that the traffic is coming from Twitter. It can be any string you choose, like utm_source=x if you're using the new branding.
• utm_campaign=social_media_ad: This is your campaign identifier. Choose a name that clearly identifies your campaign. It can be anything like utm_campaign=summer_sale.
• twclid=12345: This is a unique identifier for tracking clicks, typically provided by Twitter. It can also be any unique value you decide to use.

Step 2: Update Your Rails Controller

To capture these UTM parameters when someone clicks the link and visits your site, you need to update your Rails controller.

In your application_controller.rb, add the following method to track the UTM parameters:

class ApplicationController < ActionController::Base
  before_action :track_twitter_ad_click

  private

  def track_twitter_ad_click
    # Check if the URL parameters match what you want to track
    if params[:utm_source] == 'twitter' && params[:utm_campaign] == 'social_media_ad'
      # Track the event with Ahoy Matey
      ahoy.track "Twitter Ad Click", { campaign: params[:utm_campaign], campaign_id: params[:twclid] }
      
      # Store the campaign information in cookies for later use
      cookies[:ad_campaign] = {
        value: params[:utm_campaign],
      }
      cookies[:campaign_id] = {
        value: params[:twclid],
      }
    end
  end
end

Explanation of the Controller Method:

• before_action :track_twitter_ad_click: This ensures that the track_twitter_ad_click method is called before every action in the controller.
• params[:utm_source] == 'twitter' && params[:utm_campaign] == 'social_media_ad': This checks if the utm_source is 'twitter' and utm_campaign is 'social_media_ad'. You can replace these with any values you use in your URLs.
• ahoy.track: This method tracks an event called "Twitter Ad Click" with the campaign and campaign_id parameters.
• Cookies: Stores the campaign information in cookies so it can be accessed later (e.g., during user signup).

Step 3: Ensure Database Migrations

You need to have the appropriate tables and columns in your database to store the tracking information.

Migrations:

1. Create ahoy_visits and ahoy_events Tables:

class CreateAhoyVisitsAndEvents < ActiveRecord::Migration[7.1]
  def change
    create_table :ahoy_visits do |t|
      t.string :visit_token
      t.string :visitor_token
      t.references :user
      t.string :ip
      t.text :user_agent
      t.text :referrer
      t.string :referring_domain
      t.text :landing_page
      t.string :browser
      t.string :os
      t.string :device_type
      t.string :country
      t.string :region
      t.string :city
      t.float :latitude
      t.float :longitude
      t.string :utm_source
      t.string :utm_medium
      t.string :utm_term
      t.string :utm_content
      t.string :utm_campaign
      t.string :app_version
      t.string :os_version
      t.string :platform
      t.datetime :started_at
    end

    add_index :ahoy_visits, :visit_token, unique: true
    add_index :ahoy_visits, [:visitor_token, :started_at]

    create_table :ahoy_events do |t|
      t.references :visit
      t.references :user
      t.string :name
      t.jsonb :properties
      t.datetime :time
    end

    add_index :ahoy_events, [:name, :time]
    add_index :ahoy_events, :properties, using: :gin, opclass: :jsonb_path_ops
  end
end

2. Add campaign_id to users Table:

class AddCampaignIdToUsers < ActiveRecord::Migration[7.1]
  def change
    add_column :users, :campaign_id, :string
  end
end

Run Migrations:

rails db:migrate

Explanation of the Migrations:

• ahoy_visits table: This table stores information about each visit, such as the visitor's IP, user agent, referrer, and UTM parameters.
• ahoy_events table: This table stores events tracked by Ahoy, including the visit and user references, event name, properties, and time.
• campaign_id in users table: This column links users to specific campaigns. It helps you analyze which campaigns are leading to user signups. This could be added to any relevant model if needed. For example, you might want to track campaign_id in orders to see which campaigns lead to purchases.

Step 4: Verify the Tracking

To ensure the tracking is working, you can check the tracked data in the Rails console.

Open Rails Console:

rails console

Check Ahoy Visits:

Ahoy::Visit.all

Check Ahoy Events:

Ahoy::Event.all

Explanation of Verification:

• Ahoy::Visit.all: This command displays all visit records, showing UTM parameters and other visit details.
• Ahoy::Event.all: This command displays all event records, showing tracked events like "Twitter Ad Click".

Summary

1. Add UTM Parameters to your ad URLs to track the source and campaign.
2. Update Controller to capture and track these parameters using Ahoy Matey.
3. Run Migrations to create necessary tables and columns for storing tracking data.
4. Verify Tracking by checking the tracked data in the Rails console.

This setup allows you to track and analyze the effectiveness of your Twitter/X ads, providing insights into user engagement and campaign performance.