Class: Bitly::API::Bitlink

Inherits:
Object
  • Object
show all
Includes:
Base
Defined in:
lib/bitly/api/bitlink.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

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.



242
243
244
245
246
247
248
249
250
251
252
 
# File 'lib/bitly/api/bitlink.rb', line 242

def initialize(data:, client:, response: nil, clicks: nil)
  assign_attributes(data)
  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.



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

def clicks
  @clicks
end

#deeplinks ⇒ Object (readonly)

Returns the value of attribute deeplinks.



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

def deeplinks
  @deeplinks
end

Class Method Details

.attributes ⇒ Object 



233
234
235
 
# File 'lib/bitly/api/bitlink.rb', line 233

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/v4/#operation/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:



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

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/v4/#operation/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:



108
109
110
111
 
# File 'lib/bitly/api/bitlink.rb', line 108

def self.expand(client:, 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/bitlink/bitlink`](dev.bitly.com/v4/#operation/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:



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

def self.fetch(client:, 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/v4/#operation/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:



147
148
149
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
 
# File 'lib/bitly/api/bitlink.rb', line 147

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/v4/#operation/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:



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

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/v4/#operation/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



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

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 



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

def self.time_attributes
  [:created_at]
end

Instance Method Details

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

[‘GET /v4/bitlink/bitlink/clicks/summary`](dev.bitly.com/v4/#operation/getClicksSummaryForBitlink)

Returns:



317
318
319
 
# File 'lib/bitly/api/bitlink.rb', line 317

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/bitlink/bitlink/clicks`](dev.bitly.com/v4/#operation/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:



337
338
339
 
# File 'lib/bitly/api/bitlink.rb', line 337

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/bitlink/bitlink`](dev.bitly.com/v4/#operation/updateBitlink)

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) 


278
279
280
281
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
 
# File 'lib/bitly/api/bitlink.rb', line 278

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