Introduction - Pearset

1. Prerequisites

To follow this guide, you will need to:

2. Install and initialize the Pearset Ruby SDK

Install

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

bash

gem install pearset

Initialize

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

require 'pearset'

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

3. Create link

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

index.rb

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

res = pearset.links.create(req)

puts res.raw_response.body

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 pearset.sh if the workspace has no domains).

key

string

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

keyLength

number

The length of the short link slug. Defaults to 7 if not provided. When used with prefix, the total length of the key will be prefix.length + keyLength.

externalId

string | null

The ID of the link in your database. If set, it can be used to identify the link in future API requests (must be prefixed with ‘ext_’ when passed as a query parameter). This key is unique across your workspace.

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.

programId

string | null

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

partnerId

string | null

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

folderId

string | null

The unique ID of an existing folder to assign the short link to.

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. Defaults to false if not provided.

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. Defaults to false if not provided.

publicStats

boolean

default:false

Deprecated: Use dashboard instead. Whether the short link’s stats are publicly accessible. Defaults to false if not provided.

tagIds

string | 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 Link Previews feature. Defaults to false if not provided.

title

string | null

The custom link preview title (og:title). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

description

string | null

The custom link preview description (og:description). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

image

string | null

The custom link preview image (og:image). Will be used for Custom Link Previews if proxy is true. Learn more: https://d.to/og

video

string | null

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

rewrite

boolean

default:false

Whether the short link uses link cloaking. Defaults to false if not provided.

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.

geo

object

Geographic targeting for the short link. Allows you to redirect users based on their location.

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.

webhookIds

string[] | null

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

testVariants

object[]

An array of A/B test URLs and the percentage of traffic to send to each URL. Requires 2-4 variants with percentages between 10-90.

testStartedAt

string | null

The date and time when the tests started.

testCompletedAt

string | null

The date and time when the tests were or will be completed.

tagId

string | null

Deprecated: Use tagIds instead. The unique ID of the tag assigned to the short link.

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 Pearset’s system.

index.rb

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

res = pearset.links.create(req)

puts res.raw_response.body

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

4. Upsert link

Pearset 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

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

res = pearset.links.upsert(req)

puts res.raw_response.body

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 Pearset Ruby SDK. You can do that in two ways:

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

index.rb

req = ::OpenApiSDK::Operations::UpdateLinkRequest.new(
  link_id: "cly2p8onm000cym8200nfay7l",
  request_body: ::OpenApiSDK::Operations::UpdateLinkRequestBody.new(
    url: "https://google.us",
  ),
)

res = pearset.links.update(req)

puts res.raw_response.body

6. Retrieve analytics for link

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

index.rb

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

res = pearset.analytics.retrieve(req)

puts res.raw_response.body

7. Examples

Ruby Example

See the full example on GitHub.

​1. Prerequisites

​2. Install and initialize the Pearset Ruby SDK

Install

Initialize

​3. Create link

​4. Upsert link

​5. Update link

​6. Retrieve analytics for link

​7. Examples

Ruby Example

1. Prerequisites

2. Install and initialize the Pearset Ruby SDK

3. Create link

4. Upsert link

5. Update link

6. Retrieve analytics for link

7. Examples