Class: Bitly::API::Bitlink

Inherits:
Object
  • Object
show all
Includes:
Base
Defined in:
lib/bitly/api/bitlink.rb,
lib/bitly/api/bitlink/utils.rb,
lib/bitly/api/bitlink/deeplink.rb,
lib/bitly/api/bitlink/link_click.rb,
lib/bitly/api/bitlink/clicks_summary.rb,
lib/bitly/api/bitlink/paginated_list.rb

Overview

A Bitlink represents a shortened link within Bitly.

Defined Under Namespace

Modules: Utils Classes: ClicksSummary, Deeplink, LinkClick, List, PaginatedList

Instance Attribute Summary collapse

Attributes included from Base

#response

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Base

#assign_attributes

Constructor Details

#initialize(data:, client:, response: nil, clicks: nil) ⇒ Bitlink

Returns a new instance of Bitlink.



245
246
247
248
249
250
251
252
253
254
255
256
 
# File 'lib/bitly/api/bitlink.rb', line 245

def initialize(data:, client:, response: nil, clicks: nil)
  assign_attributes(data)
  @id = Utils.normalise_bitlink(bitlink: @id)
  if data["deeplinks"]
    @deeplinks = data["deeplinks"].map { |data| Deeplink.new(data: data) }
  else
    @deeplinks = []
  end
  @clicks = clicks
  @client = client
  @response = response
end

Instance Attribute Details

#clicks ⇒ Object (readonly)

Returns the value of attribute clicks.



243
244
245
 
# File 'lib/bitly/api/bitlink.rb', line 243

def clicks
  @clicks
end

#deeplinks ⇒ Object (readonly)

Returns the value of attribute deeplinks.



243
244
245
 
# File 'lib/bitly/api/bitlink.rb', line 243

def deeplinks
  @deeplinks
end

Class Method Details

.attributes ⇒ Object 



236
237
238
 
# File 'lib/bitly/api/bitlink.rb', line 236

def self.attributes
  [:archived, :tags, :title, :created_by, :long_url, :client_id, :custom_bitlinks, :link, :id]
end

.create(client:, long_url:, domain: nil, group_guid: nil, title: nil, tags: nil, deeplinks: nil) ⇒ Bitly::API::Bitlink

Creates a new Bitlink from a long URL. Similar to #shorten but takes more parameters. [‘POST /v4/bitlinks`](dev.bitly.com/api-reference/#createFullBitlink)

Examples:

bitlink = Bitly::API::Bitlink.create(client: client, long_url: long_url)

Parameters:

  • client (Bitly::API::Client) —

    An authorized API client

  • long_url (String) —

    A long URL that you want shortened

  • domain (String) (defaults to: nil) —

    The bitly domain you want to shorten, API default is “bit.ly”

  • group_guid (String) (defaults to: nil) —

    The GUID of the group for which you want to shorten this URL

  • title (String) (defaults to: nil) —

    A descriptive title for the link

  • tags (Array<String>) (defaults to: nil) —

    Some tags for the Bitlink

  • deeplinks (Array<Bitly::API::Bitlink::Deeplink>) (defaults to: nil)

Returns:



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/bitly/api/bitlink.rb', line 66

def self.create(client:, long_url:, domain: nil, group_guid: nil, title: nil, tags: nil, deeplinks: nil)
  response = client.request(
    path: "/bitlinks",
    method: "POST",
    params: {
      "long_url" => long_url,
      "domain" => domain,
      "group_guid" => group_guid,
      "title" => title,
      "tags" => tags,
      "deeplinks" => deeplinks
    }
  )
  new(data: response.body, client: client, response: response)
end

.expand(client:, bitlink:) ⇒ Bitly::API::Bitlink

Return public information about a bitlink [‘POST /v4/expand`](dev.bitly.com/api-reference/#expandBitlink)

Examples:

bitlink = Bitly::API::Bitlink.expand(client: client, bitlink: "bit.ly/example")

Parameters:

  • client (Bitly::API::Client) —

    An authorized API client

  • bitlink (String) —

    The bitlink you want information about

Returns:



110
111
112
113
114
 
# File 'lib/bitly/api/bitlink.rb', line 110

def self.expand(client:, bitlink:)
  bitlink = Utils.normalise_bitlink(bitlink: bitlink)
  response = client.request(path: "/expand", method: "POST", params: { "bitlink_id" => bitlink })
  new(data: response.body, client: client, response: response)
end

.fetch(client:, bitlink:) ⇒ Bitly::API::Bitlink

Return information about a bitlink [‘GET /v4/bitlinks/bitlink`](dev.bitly.com/api-reference/#getBitlink)

Examples:

bitlink = Bitly::API::Bitlink.fetch(client: client, bitlink: "bit.ly/example")

Parameters:

  • client (Bitly::API::Client) —

    An authorized API client

  • bitlink (String) —

    The bitlink you want information about

Returns:



93
94
95
96
97
 
# File 'lib/bitly/api/bitlink.rb', line 93

def self.fetch(client:, bitlink:)
  bitlink = Utils.normalise_bitlink(bitlink: bitlink)
  response = client.request(path: "/bitlinks/#{bitlink}")
  new(data: response.body, client: client, response: response)
end

.list(client:, group_guid:, size: nil, page: nil, keyword: nil, query: nil, created_before: nil, created_after: nil, modified_after: nil, archived: nil, deeplinks: nil, domain_deeplinks: nil, campaign_guid: nil, channel_guid: nil, custom_bitlink: nil, tags: nil, encoding_login: nil) ⇒ Bitly::API::Bitlink::PaginatedList

Retrieve a list of bitlinks by group [‘GET /v4/groups/group_guid/bitlinks`](dev.bitly.com/api-reference/#getBitlinksByGroup)

Examples:

bitlinks = Bitly::API::Bitlink.list(client: client, group_guid: guid)

Parameters:

  • client (Bitly::API::Client) —

    An authorized API client

  • group_guid (String) —

    The group guid for which you want bitlinks

  • size (Integer) (defaults to: nil) —

    The number of Bitlinks to return, max 100

  • page (Integer) (defaults to: nil) —

    The page of bitlinks to request

  • keyword (String) (defaults to: nil) —

    Custom keyword to filter on history entries

  • query (String) (defaults to: nil) —

    A value to search for Bitlinks

  • created_before (Integer) (defaults to: nil) —

    Timestamp as an integer unix epoch

  • created_after (Integer) (defaults to: nil) —

    Timestamp as an integer unix epoch

  • modified_after (Integer) (defaults to: nil) —

    Timestamp as an integer unix epoch

  • archived (String) (defaults to: nil) —

    Whether or not to include archived Bitlinks. One of “on”, “off” or “both”. Defaults to “off”.

  • deeplinks (String) (defaults to: nil) —

    Filter to only Bitlinks that contain deeplinks. One of “on”, “off” or “both”. Defaults to “both”.

  • domain_deeplinks (String) (defaults to: nil) —

    Filter to only Bitlinks that contain deeplinks configured with a custom domain. One of “on”, “off” or “both”. Defaults to “both”.

  • campaign_guid (String) (defaults to: nil) —

    Filter to return only links for the given campaign GUID, can be provided

  • channel_guid (String) (defaults to: nil) —

    Filter to return only links for the given channel GUID, can be provided, overrides all other parameters

  • custom_bitlink (String) (defaults to: nil) —

    Filter to return only custom Bitlinks. One of “on”, “off” or “both”. Defaults to “both”.

  • tags (Array<String>) (defaults to: nil) —

    Filter by the given tags.

  • encoding_login (Array<String>) (defaults to: nil) —

    Filter by the login of the authenticated user that created the Bitlink.

Returns:



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/bitly/api/bitlink.rb', line 150

def self.list(
  client:,
  group_guid:,
  size: nil,
  page: nil,
  keyword: nil,
  query: nil,
  created_before: nil,
  created_after: nil,
  modified_after: nil,
  archived: nil,
  deeplinks: nil,
  domain_deeplinks: nil,
  campaign_guid: nil,
  channel_guid: nil,
  custom_bitlink: nil,
  tags: nil,
  encoding_login: nil
)
  params = {
    "size" => size,
    "page" => page,
    "keyword" => keyword,
    "query" => query,
    "created_before" => created_before,
    "created_after" => created_after,
    "modified_after" => modified_after,
    "archived" => archived,
    "deeplinks" => deeplinks,
    "domain_deeplinks" => domain_deeplinks,
    "campaign_guid" => campaign_guid,
    "channel_guid" => channel_guid,
    "custom_bitlink" => custom_bitlink,
    "tags" => tags,
    "encoding_login" => 
  }
  response = client.request(path: "/groups/#{group_guid}/bitlinks", params: params)
  bitlinks = response.body["links"].map do |link|
    new(data: link, client: client)
  end
  PaginatedList.new(items: bitlinks, response: response, client: client)
end

.shorten(client:, long_url:, domain: nil, group_guid: nil) ⇒ Bitly::API::Bitlink

Shortens a long url. [‘POST /v4/shorten`](dev.bitly.com/api-reference/#createBitlink)

Examples:

bitlink = Bitly::API::Bitlink.shorten(client: client, long_url: long_url)

Parameters:

  • client (Bitly::API::Client) —

    An authorized API client

  • long_url (String) —

    A long URL that you want shortened

  • domain (String) (defaults to: nil) —

    The bitly domain you want to shorten, API default is “bit.ly”

  • group_guid (String) (defaults to: nil) —

    The GUID of the group for which you want to shorten this URL

Returns:



35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/bitly/api/bitlink.rb', line 35

def self.shorten(client:, long_url:, domain: nil, group_guid: nil)
  response = client.request(
    path: "/shorten",
    method: "POST",
    params: {
      "long_url" => long_url,
      "domain" => domain,
      "group_guid" => group_guid
    })
  new(data: response.body, client: client, response: response)
end

.sorted_list(client:, group_guid:, sort: "clicks", unit: nil, units: nil, unit_reference: nil, size: nil) ⇒ Object

Returns a list of Bitlinks sorted by clicks. [‘GET /v4/groups/group_guid/bitlinks/sort`](dev.bitly.com/api-reference/#getSortedBitlinks)

The API returns a separate list of the links and the click counts, but this method assigns the number of clicks for each link to the Bitlink object and sorts the resulting list in descending order.

Sorted lists are not paginated, so do not have any pagination detail.

Examples:

links = Bitly::API::Bitlink.sorted_list(client: client, group_guid: guid)

Parameters:

  • client (Bitly::API::Client) —

    An authorized API client

  • group_guid (String) —

    The group for which you want to return links

  • sort (String) (defaults to: "clicks") —

    The data to sort on. Default and only option is “clicks”.

  • unit (String) (defaults to: nil) —

    A unit of time. Default is “day” and can be “minute”, “hour”, “day”, “week” or “month”

  • units (Integer) (defaults to: nil) —

    An integer representing the time units to query data for. pass -1 to return all units of time. Defaults to -1.

  • unit_reference (String) (defaults to: nil) —

    An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.

  • size (Integer) (defaults to: nil) —

    The number of links to be returned. Defaults to 50



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/bitly/api/bitlink.rb', line 220

def self.sorted_list(client:, group_guid:, sort: "clicks", unit: nil, units: nil, unit_reference: nil, size: nil)
  params = {
    "unit" => unit,
    "units" => units,
    "unit_reference" => unit_reference,
    "size" => size
  }
  response = client.request(path: "/groups/#{group_guid}/bitlinks/#{sort}", params: params)
  link_clicks = response.body["sorted_links"]
  bitlinks = response.body["links"].map do |link|
    clicks = link_clicks.find { |c| c["id"] == link["id"] }["clicks"]
    new(data: link, client: client, clicks: clicks)
  end.sort { |a, b| b.clicks <=> a.clicks }
  List.new(items: bitlinks, response: response)
end

.time_attributes ⇒ Object 



239
240
241
 
# File 'lib/bitly/api/bitlink.rb', line 239

def self.time_attributes
  [:created_at]
end

Instance Method Details

#click_metrics_by_country(unit: nil, units: nil, unit_reference: nil, size: nil) ⇒ Bitly::API::ClickMetric::List

Get metrics for a Bitlink by country [‘GET /v4/bitlinks/bitlink/countries`](dev.bitly.com/api-reference/#getMetricsForBitlinkByCountries)

Parameters:

  • unit (String) (defaults to: nil) —

    A unit of time. Default is “day” and can be “minute”, “hour”, “day”, “week” or “month”

  • units (Integer) (defaults to: nil) —

    An integer representing the time units to query data for. pass -1 to return all units of time. Defaults to -1.

  • unit_reference (String) (defaults to: nil) —

    An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.

  • size (Integer) (defaults to: nil) —

    The number of links to be returned. Defaults to 50

Returns:



359
360
361
 
# File 'lib/bitly/api/bitlink.rb', line 359

def click_metrics_by_country(unit: nil, units: nil, unit_reference: nil, size: nil)
  ClickMetric.list_countries_by_bitlink(client: @client, bitlink: id, unit: unit, units: units, unit_reference: unit_reference, size: size)
end

#clicks_summary(unit: nil, units: nil, unit_reference: nil, size: nil) ⇒ Bitly::API::Bitlink::ClicksSummary

[‘GET /v4/bitlinks/bitlink/clicks/summary`](dev.bitly.com/api-reference/#getClicksSummaryForBitlink)

Returns:



321
322
323
 
# File 'lib/bitly/api/bitlink.rb', line 321

def clicks_summary(unit: nil, units: nil, unit_reference: nil, size: nil)
  ClicksSummary.fetch(client: @client, bitlink: id, unit: unit, units: units, unit_reference: unit_reference, size: size)
end

#link_clicks(unit: nil, units: nil, unit_reference: nil, size: nil) ⇒ Bitly::API::Bitlink::LinkClick::List

Get the clicks for the bitlink. [‘GET /v4/bitlinks/bitlink/clicks`](dev.bitly.com/api-reference/#getClicksForBitlink)

Parameters:

  • sort (String) —

    The data to sort on. Default and only option is “clicks”.

  • unit (String) (defaults to: nil) —

    A unit of time. Default is “day” and can be “minute”, “hour”, “day”, “week” or “month”

  • units (Integer) (defaults to: nil) —

    An integer representing the time units to query data for. pass -1 to return all units of time. Defaults to -1.

  • unit_reference (String) (defaults to: nil) —

    An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.

  • size (Integer) (defaults to: nil) —

    The number of links to be returned. Defaults to 50

Returns:



341
342
343
 
# File 'lib/bitly/api/bitlink.rb', line 341

def link_clicks(unit: nil, units: nil, unit_reference: nil, size: nil)
  LinkClick.list(client: @client, bitlink: id, unit: unit, units: units, unit_reference: unit_reference, size: size)
end

#update(archived: nil, tags: nil, created_at: nil, title: nil, deeplinks: nil, created_by: nil, long_url: nil, client_id: nil, custom_bitlinks: nil, link: nil, id: nil, references: nil) ⇒ Object

Update the Bitlink. [‘PATCH /v4/bitlinks/bitlink`](dev.bitly.com/api-reference/#getClicksSummaryForBitlink)

The parameters listed below are from the documentation. Some only work if you have a Bitly Pro account.

Examples:

bitlink.update(title: "New title")

Parameters:

  • archived (Boolean) (defaults to: nil)
  • tags (Array<String>) (defaults to: nil)
  • created_at (String) (defaults to: nil)
  • title (String) (defaults to: nil)
  • deeplinks (Array<Bitly::API::Bitlink::Deeplink>) (defaults to: nil)
  • created_by (String) (defaults to: nil)
  • long_url (String) (defaults to: nil)
  • client_id (String) (defaults to: nil)
  • custom_bitlinks (Array<String>) (defaults to: nil)
  • link (String) (defaults to: nil)
  • id (String) (defaults to: nil)
  • references (Hash<String, String>) (defaults to: nil) 


282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/bitly/api/bitlink.rb', line 282

def update(
  archived: nil,
  tags: nil,
  created_at: nil,
  title: nil,
  deeplinks: nil,
  created_by: nil,
  long_url: nil,
  client_id: nil,
  custom_bitlinks: nil,
  link: nil,
  id: nil,
  references: nil
)
  @response = @client.request(
    path: "/bitlinks/#{@id}",
    method: "PATCH",
    params: {
      "archived" => archived,
      "tags" => tags,
      "created_at" => created_at,
      "title" => title,
      "deeplinks" => deeplinks,
      "created_by" => created_by,
      "long_url" =>long_url ,
      "client_id" => client_id,
      "custom_bitlinks" => custom_bitlinks,
      "link" => link,
      "id" => id,
      "references" => references
    }
  )
  assign_attributes(@response.body)
  self
end