Ruby on Rails

Learn how to integrate Dub with Ruby on Rails.

1. Prerequisites

To follow this guide, you will need to:

• Create a Dub account
• Create an API key

2. Install and initialize the Dub Ruby SDK

1. Install

   To install the Dub Ruby SDK, run the following command:

   bash

   gem install dub
   
2. Initialize

   Initialize the Dub Ruby SDK by creating a new instance of the Dub struct.

   class LinksController < ApplicationController
     require 'dub'
   
     before_action :initialize_dub
   
     def initialize_dub
       @dub = ::OpenApiSDK::Dub.new
       @dub.config_security(
         ::OpenApiSDK::Shared::Security.new(
           token: ENV['DUB_API_KEY']
         )
       )
     end
   end
   

3. Create link

Let’s create a short link using the Dub Ruby SDK.

links_controller.rb

def create
  req = ::OpenApiSDK::Operations::CreateLinkRequest.new(
    request_body: ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
      url: 'https://google.com'
    )
  )

  res = @dub.links.create(req)

  render json: res.raw_response.body
end

Full list of available attributes for the Link model

url · string · required

The destination URL of the short link.

domain · string

The domain of the short link. If not provided, the primary domain for the workspace will be used (or dub.sh if the workspace has no domains).

key · string

The short link slug. If not provided, a random 7-character slug will be generated.

externalId · string | null

This is the ID of the link in your database. If set, it can be used to identify the link in the future.

tenantId · string | null

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant.

prefix · string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

trackConversion · boolean · default: false

Whether to track conversions for the short link.

identifier · string | null

The identifier of the short link that is unique across your workspace. If set, it can be used to identify your short link for client-side click tracking.

archived · boolean · default: false

Whether the short link is archived.

publicStats · boolean · default: false

Whether the short link’s stats are publicly accessible.

tagIds · string

The unique IDs of the tags assigned to the short link.

tagNames · string | string[]

The unique name of the tags assigned to the short link (case insensitive).

comments · string | null

The comments for the short link.

expiresAt · string | null

The date and time when the short link will expire at.

expiredUrl · string | null

The URL to redirect to when the short link has expired.

password · string | null

The password required to access the destination URL of the short link.

proxy · boolean · default: false

Whether the short link uses Custom Social Media Cards feature.

title · string | null

The title of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

description · string | null

The description of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

image · string | null

The image of the short link generated via api.dub.co/metatags. Will be used for Custom Social Media Cards if proxy is true.

video · string | null

The custom link preview video (og:video). Will be used for Custom Social Media Cards if proxy is true. Learn more: https://d.to/og

rewrite · boolean · default: false

Whether the short link uses link cloaking.

ios · string | null

The iOS destination URL for the short link for iOS device targeting.

android · string | null

The Android destination URL for the short link for Android device targeting.

doIndex · boolean · default: false

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

utm_source · string | null

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.

utm_medium · string | null

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.

utm_campaign · string | null

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.

utm_term · string | null

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.

utm_content · string | null

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.

ref · string | null

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL.

programId · string | null

The ID of the program the short link is associated with.

webhookIds · string[] | null

An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.

Optionally, you can also pass an externalId field which is a unique identifier for the link in your own database to associate it with the link in Dub’s system.

links_controller.rb

def create
  req = ::OpenApiSDK::Operations::CreateLinkRequest.new(
    request_body: ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
      url: 'https://google.com',
      external_id: '12345'
    )
  )

  res = @dub.links.create(req)

  render json: res.raw_response.body
end

This will let you easily update the link or retrieve analytics for it later on using the externalId instead of the Dub linkId.

4. Upsert link

Dub Ruby SDK provides a method to upsert a link – where an existing link is updated if it exists, or a new link is created if it doesn’t. so you don’t have to worry about checking if the link already exists.

links_controller.rb

def upsert
  req = ::OpenApiSDK::Operations::UpsertLinkRequest.new(
    request_body: ::OpenApiSDK::Operations::UpsertLinkRequestBody.new(
      url: "https://google.com",
    ),
  )

  res = @dub.links.upsert(req)

  render json: res.raw_response.body
end

This way, you won’t have to worry about checking if the link already exists when you’re creating it.

5. Update link

Let’s update an existing link using the Dub Ruby SDK.

You can do that in two ways:

• Using the link’s linkId in Dub’s system.
• Using the link’s externalId in your own database (prefixed with ext_).

links_controller.rb

def update
  req = ::OpenApiSDK::Operations::UpdateLinkRequest.new(
    link_id: 'clx1gvi9o0005hf5momm6f7hj',
    request_body: ::OpenApiSDK::Operations::UpdateLinkRequestBody.new(
      url: 'https://google.uk'
    )
  )

  res = @dub.links.update(req)

  render json: res.raw_response.body
end

6. Retrieve analytics for link

Let’s retrieve analytics for a link using the Dub Ruby SDK.

index.rb

def analytics
  req = ::OpenApiSDK::Operations::RetrieveAnalyticsRequest.new(
    link_id: "clx1gvi9o0005hf5momm6f7hj",
    interval: ::OpenApiSDK::Operations::Interval::SEVEND,
    group_by: ::OpenApiSDK::Operations::GroupBy::TIMESERIES
  )

  res = @dub.analytics.retrieve(req)

  render json: res.raw_response.body
end

7. Examples

Rails Example

See the full example on GitHub.