Sinatra

Learn how to integrate Dub with Sinatra.

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.

index.rb

require "sinatra"
require "dub"

dub = ::OpenApiSDK::Dub.new
dub.config_security(
  ::OpenApiSDK::Shared::Security.new(
    token: ENV['DUB_API_KEY'],
  )
)

3. Create link

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

index.rb

post "/links" do
  req = ::OpenApiSDK::Operations::CreateLinkRequest.new(
    request_body: ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
      url: 'https://google.com'
    )
  )

  res = dub.links.create(req)

  content_type :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.

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.

tagId

string | null

The unique ID of the tag assigned to the short link. This field is deprecated – use tagIds instead.

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.

index.rb

post "/links" do
  req = ::OpenApiSDK::Operations::CreateLinkRequest.new(
    request_body: ::OpenApiSDK::Operations::CreateLinkRequestBody.new(
      url: 'https://google.com',
      external_id: '12345'
    )
  )

  res = dub.links.create(req)

  content_type :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.

index.rb

put "/links" do
  req = ::OpenApiSDK::Operations::UpsertLinkRequest.new(
    request_body: ::OpenApiSDK::Operations::UpsertLinkRequestBody.new(
      url: "https://google.com",
    ),
  )

  res = dub.links.upsert(req)

  content_type :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_).

index.rb

patch "/links" do
  req = ::OpenApiSDK::Operations::UpdateLinkRequest.new(
    link_id: "clyci5h0w000511sjmu0tyjv9",
    request_body: ::OpenApiSDK::Operations::UpdateLinkRequestBody.new(
      url: 'https://google.uk'
    )
  )

  res = dub.links.update(req)

  content_type :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

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

  res = dub.analytics.retrieve(req)

  content_type :json
  res.raw_response.body
end

7. Examples

Sinatra Example

See the full example on GitHub.