Class: Umami::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/umami/client.rb

Overview

The Client class provides methods to interact with the Umami API.

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Client

Initialize a new Umami API client

Parameters:

  • options (Hash) (defaults to: {}) —

    options to create a client with.

Options Hash (options):

  • :uri_base (String) —

    The base URI for the Umami API

  • :request_timeout (Integer) —

    Request timeout in seconds

  • :access_token (String) —

    Access token for authentication

  • :username (String) —

    Username for authentication (only for self-hosted instances)

  • :password (String) —

    Password for authentication (only for self-hosted instances)



19
20
21
22
23
24
25
26
27
28
29
30
 
# File 'lib/umami/client.rb', line 19

def initialize(options = {})
  @config = options[:config] || Umami.configuration
  @uri_base = options[:uri_base] || @config.uri_base
  @request_timeout = options[:request_timeout] || @config.request_timeout
  @access_token = options[:access_token] || @config.access_token
  @username = options[:username] || @config.username
  @password = options[:password] || @config.password

  validate_client_options

  authenticate if @access_token.nil?
end

Instance Attribute Details

#request_timeout ⇒ Object (readonly)

Returns the value of attribute request_timeout.



9
10
11
 
# File 'lib/umami/client.rb', line 9

def request_timeout
  @request_timeout
end

#uri_base ⇒ Object (readonly)

Returns the value of attribute uri_base.



9
10
11
 
# File 'lib/umami/client.rb', line 9

def uri_base
  @uri_base
end

Instance Method Details

#add_team_user(team_id, user_id, role) ⇒ Hash

Add a user to a team

Parameters:

  • team_id (String) —

    The team's ID

  • user_id (String) —

    The user's ID

  • role (String) —

    The user's role in the team

Returns:

  • (Hash) —

    Added team user details

See Also:



241
242
243
 
# File 'lib/umami/client.rb', line 241

def add_team_user(team_id, user_id, role)
  post("/api/teams/#{team_id}/users", { userId: user_id, role: role })
end

#cloud? ⇒ Boolean

Check if the client is configured for Umami Cloud

Returns:

  • (Boolean) —

    true if using Umami Cloud, false otherwise



35
36
37
 
# File 'lib/umami/client.rb', line 35

def cloud?
  @uri_base == Umami::Configuration::UMAMI_CLOUD_URL
end

#create_team(name) ⇒ Hash

Create a new team

Parameters:

  • name (String) —

    The team's name

Returns:

  • (Hash) —

    Created team details

See Also:



164
165
166
 
# File 'lib/umami/client.rb', line 164

def create_team(name)
  post("/api/teams", { name: name })
end

#create_user(username, password, role) ⇒ Hash

Create a new user

Parameters:

  • username (String) —

    The user's username

  • password (String) —

    The user's password

  • role (String) —

    The user's role ('admin' or 'user')

Returns:

  • (Hash) —

    Created user details

See Also:



86
87
88
 
# File 'lib/umami/client.rb', line 86

def create_user(username, password, role)
  post("/api/users", { username: username, password: password, role: role })
end

#create_website(params = {}) ⇒ Hash

Create a new website

Parameters:

  • params (Hash) (defaults to: {}) —

    Website parameters

Options Hash (params):

  • :domain (String) —

    The full domain of the tracked website

  • :name (String) —

    The name of the website in Umami

  • :shareId (String) —

    A unique string to enable a share url (optional)

  • :teamId (String) —

    The ID of the team the website will be created under (optional)

Returns:

  • (Hash) —

    Created website details

See Also:



314
315
316
 
# File 'lib/umami/client.rb', line 314

def create_website(params = {})
  post("/api/websites", params)
end

#delete_team(team_id) ⇒ String

Delete a team

Parameters:

  • team_id (String) —

    The team's ID

Returns:

  • (String) —

    Confirmation message

See Also:



216
217
218
 
# File 'lib/umami/client.rb', line 216

def delete_team(team_id)
  delete("/api/teams/#{team_id}")
end

#delete_team_user(team_id, user_id) ⇒ String

Remove a user from a team

Parameters:

  • team_id (String) —

    The team's ID

  • user_id (String) —

    The user's ID

Returns:

  • (String) —

    Confirmation message

See Also:



272
273
274
 
# File 'lib/umami/client.rb', line 272

def delete_team_user(team_id, user_id)
  delete("/api/teams/#{team_id}/users/#{user_id}")
end

#delete_user(user_id) ⇒ String

Delete a user

Parameters:

  • user_id (String) —

    The user's ID

Returns:

  • (String) —

    Confirmation message

See Also:



125
126
127
 
# File 'lib/umami/client.rb', line 125

def delete_user(user_id)
  delete("/api/users/#{user_id}")
end

#delete_website(website_id) ⇒ String

Delete a website

Parameters:

  • website_id (String) —

    The website's ID

Returns:

  • (String) —

    Confirmation message

See Also:



345
346
347
 
# File 'lib/umami/client.rb', line 345

def delete_website(website_id)
  delete("/api/websites/#{website_id}")
end

#event_data_events(website_id, params = {}) ⇒ Array<Hash>

Get event data events

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date

  • :endAt (Integer) —

    Timestamp (in ms) of end date

  • :event (String) —

    Event Name filter

Returns:

  • (Array<Hash>) —

    Event data events

See Also:



465
466
467
 
# File 'lib/umami/client.rb', line 465

def event_data_events(website_id, params = {})
  get("/api/event-data/events", params.merge(websiteId: website_id))
end

#event_data_fields(website_id, params = {}) ⇒ Array<Hash>

Get event data fields

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date

  • :endAt (Integer) —

    Timestamp (in ms) of end date

Returns:

  • (Array<Hash>) —

    Event data fields

See Also:



480
481
482
 
# File 'lib/umami/client.rb', line 480

def event_data_fields(website_id, params = {})
  get("/api/event-data/fields", params.merge(websiteId: website_id))
end

#event_data_stats(website_id, params = {}) ⇒ Array<Hash>

Get event data stats

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date

  • :endAt (Integer) —

    Timestamp (in ms) of end date

Returns:

  • (Array<Hash>) —

    Event data stats

See Also:



492
493
494
 
# File 'lib/umami/client.rb', line 492

def event_data_stats(website_id, params = {})
  get("/api/event-data/stats", params.merge(websiteId: website_id))
end

#join_team(access_code) ⇒ Hash

Join a team

Parameters:

  • access_code (String) —

    The team's access code

Returns:

  • (Hash) —

    Joined team details

See Also:



186
187
188
 
# File 'lib/umami/client.rb', line 186

def join_team(access_code)
  post("/api/teams/join", { accessCode: access_code })
end

#reset_website(website_id) ⇒ String

Reset a website's data

Parameters:

  • website_id (String) —

    The website's ID

Returns:

  • (String) —

    Confirmation message

See Also:



354
355
356
 
# File 'lib/umami/client.rb', line 354

def reset_website(website_id)
  post("/api/websites/#{website_id}/reset")
end

#self_hosted? ⇒ Boolean

Check if the client is configured for a self-hosted Umami instance

Returns:

  • (Boolean) —

    true if using a self-hosted instance, false otherwise



42
43
44
 
# File 'lib/umami/client.rb', line 42

def self_hosted?
  !cloud?
end

#send_event(payload) ⇒ Hash

Send an event

Parameters:

  • payload (Hash) —

    Event payload

Options Hash (payload):

  • :hostname (String) —

    Name of host

  • :language (String) —

    Language of visitor (ex. "en-US")

  • :referrer (String) —

    Referrer URL

  • :screen (String) —

    Screen resolution (ex. "1920x1080")

  • :title (String) —

    Page title

  • :url (String) —

    Page URL

  • :website (String) —

    Website ID

  • :name (String) —

    Name of the event

  • :data (Hash) —

    Additional data for the event

Returns:

  • (Hash) —

    Response from the server

See Also:



512
513
514
 
# File 'lib/umami/client.rb', line 512

def send_event(payload)
  post("/api/send", { type: "event", payload: payload })
end

#team(team_id) ⇒ Hash

Get a team by ID

Parameters:

  • team_id (String) —

    The team's ID

Returns:

  • (Hash) —

    Team details

See Also:



195
196
197
 
# File 'lib/umami/client.rb', line 195

def team(team_id)
  get("/api/teams/#{team_id}")
end

#team_user(team_id, user_id) ⇒ Hash

Get a user in a team

Parameters:

  • team_id (String) —

    The team's ID

  • user_id (String) —

    The user's ID

Returns:

  • (Hash) —

    Team user details

See Also:



251
252
253
 
# File 'lib/umami/client.rb', line 251

def team_user(team_id, user_id)
  get("/api/teams/#{team_id}/users/#{user_id}")
end

#team_users(team_id, params = {}) ⇒ Array<Hash>

Get all users in a team

Parameters:

  • team_id (String) —

    The team's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :query (String) —

    Search text

  • :page (Integer) —

    Page number

  • :pageSize (Integer) —

    Number of results per page

  • :orderBy (String) —

    Column to order by

Returns:

  • (Array<Hash>) —

    List of team users

See Also:



230
231
232
 
# File 'lib/umami/client.rb', line 230

def team_users(team_id, params = {})
  get("/api/teams/#{team_id}/users", params)
end

#team_websites(team_id, params = {}) ⇒ Array<Hash>

Get all websites for a team

Parameters:

  • team_id (String) —

    The team's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :query (String) —

    Search text

  • :page (Integer) —

    Page number

  • :pageSize (Integer) —

    Number of results per page

  • :orderBy (String) —

    Column to order by

Returns:

  • (Array<Hash>) —

    List of team websites

See Also:



286
287
288
 
# File 'lib/umami/client.rb', line 286

def team_websites(team_id, params = {})
  get("/api/teams/#{team_id}/websites", params)
end

#teams(params = {}) ⇒ Array<Hash>

Get all teams

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :query (String) —

    Search text

  • :page (Integer) —

    Page number

  • :pageSize (Integer) —

    Number of results per page

  • :orderBy (String) —

    Column to order by

Returns:

  • (Array<Hash>) —

    List of teams

See Also:



177
178
179
 
# File 'lib/umami/client.rb', line 177

def teams(params = {})
  get("/api/teams", params)
end

#update_team(team_id, params = {}) ⇒ Hash

Update a team

Parameters:

  • team_id (String) —

    The team's ID

  • params (Hash) (defaults to: {}) —

    Team parameters to update

Options Hash (params):

  • :name (String) —

    The team's new name

  • :accessCode (String) —

    The team's new access code

Returns:

  • (Hash) —

    Updated team details

See Also:



207
208
209
 
# File 'lib/umami/client.rb', line 207

def update_team(team_id, params = {})
  post("/api/teams/#{team_id}", params)
end

#update_team_user(team_id, user_id, role) ⇒ String

Update a user's role in a team

Parameters:

  • team_id (String) —

    The team's ID

  • user_id (String) —

    The user's ID

  • role (String) —

    The user's new role

Returns:

  • (String) —

    Confirmation message

See Also:



262
263
264
 
# File 'lib/umami/client.rb', line 262

def update_team_user(team_id, user_id, role)
  post("/api/teams/#{team_id}/users/#{user_id}", { role: role })
end

#update_user(user_id, params = {}) ⇒ Hash

Update a user

Parameters:

  • user_id (String) —

    The user's ID

  • params (Hash) (defaults to: {}) —

    User parameters to update

Options Hash (params):

  • :username (String) —

    The user's new username

  • :password (String) —

    The user's new password

  • :role (String) —

    The user's new role

Returns:

  • (Hash) —

    Updated user details

See Also:



116
117
118
 
# File 'lib/umami/client.rb', line 116

def update_user(user_id, params = {})
  post("/api/users/#{user_id}", params)
end

#update_website(website_id, params = {}) ⇒ Hash

Update a website

Parameters:

  • website_id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Website parameters to update

Options Hash (params):

  • :name (String) —

    The name of the website in Umami

  • :domain (String) —

    The full domain of the tracked website

  • :shareId (String) —

    A unique string to enable a share url

Returns:

  • (Hash) —

    Updated website details

See Also:



336
337
338
 
# File 'lib/umami/client.rb', line 336

def update_website(website_id, params = {})
  post("/api/websites/#{website_id}", params)
end

#user(user_id) ⇒ Hash

Get a user by ID

Parameters:

  • user_id (String) —

    The user's ID

Returns:

  • (Hash) —

    User details

See Also:



103
104
105
 
# File 'lib/umami/client.rb', line 103

def user(user_id)
  get("/api/users/#{user_id}")
end

#user_teams(user_id, params = {}) ⇒ Array<Hash>

Get all teams for a user

Parameters:

  • user_id (String) —

    The user's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :query (String) —

    Search text

  • :page (Integer) —

    Page number

  • :pageSize (Integer) —

    Number of results per page

  • :orderBy (String) —

    Column to order by

Returns:

  • (Array<Hash>) —

    List of user's teams

See Also:



153
154
155
 
# File 'lib/umami/client.rb', line 153

def user_teams(user_id, params = {})
  get("/api/users/#{user_id}/teams", params)
end

#user_websites(user_id, params = {}) ⇒ Array<Hash>

Get all websites for a user

Parameters:

  • user_id (String) —

    The user's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :query (String) —

    Search text

  • :page (Integer) —

    Page number

  • :pageSize (Integer) —

    Number of results per page

  • :orderBy (String) —

    Column to order by

Returns:

  • (Array<Hash>) —

    List of user's websites

See Also:



139
140
141
 
# File 'lib/umami/client.rb', line 139

def user_websites(user_id, params = {})
  get("/api/users/#{user_id}/websites", params)
end

#users ⇒ Array<Hash>

Get all users (admin access required)

Returns:

  • (Array<Hash>) —

    List of all users

See Also:



94
95
96
 
# File 'lib/umami/client.rb', line 94

def users
  get("/api/admin/users")
end

#verify_token ⇒ Hash

Verify the authentication token

Returns:

  • (Hash) —

    Token verification result

See Also:



50
51
52
 
# File 'lib/umami/client.rb', line 50

def verify_token
  get("/api/auth/verify")
end

#website(id) ⇒ Hash

Get a website by ID

Parameters:

  • id (String) —

    The website's ID

Returns:

  • (Hash) —

    Website details

See Also:



323
324
325
 
# File 'lib/umami/client.rb', line 323

def website(id)
  get("/api/websites/#{id}")
end

#website_active_visitors(id) ⇒ Hash

Get active visitors for a website

Parameters:

  • id (String) —

    The website's ID

Returns:

  • (Hash) —

    Number of active visitors

See Also:



388
389
390
 
# File 'lib/umami/client.rb', line 388

def website_active_visitors(id)
  get("/api/websites/#{id}/active")
end

#website_events(id, params = {}) ⇒ Array<Hash>

Get website events

Parameters:

  • id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date

  • :endAt (Integer) —

    Timestamp (in ms) of end date

  • :unit (String) —

    Time unit (year | month | hour | day)

  • :timezone (String) —

    Timezone (ex. America/Los_Angeles)

  • :url (String) —

    Name of URL

Returns:

  • (Array<Hash>) —

    Website events

See Also:



403
404
405
 
# File 'lib/umami/client.rb', line 403

def website_events(id, params = {})
  get("/api/websites/#{id}/events", params)
end

#website_metrics(id, params = {}) ⇒ Array<Hash>

Get website metrics

Parameters:

  • id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date

  • :endAt (Integer) —

    Timestamp (in ms) of end date

  • :type (String) —

    Metrics type (url | referrer | browser | os | device | country | event)

  • :url (String) —

    Name of URL

  • :referrer (String) —

    Name of referrer

  • :title (String) —

    Name of page title

  • :query (String) —

    Name of query

  • :event (String) —

    Name of event

  • :os (String) —

    Name of operating system

  • :browser (String) —

    Name of browser

  • :device (String) —

    Name of device

  • :country (String) —

    Name of country

  • :region (String) —

    Name of region/state/province

  • :city (String) —

    Name of city

  • :language (String) —

    Name of language

  • :limit (Integer) —

    Number of results to return (default: 500)

Returns:

  • (Array<Hash>) —

    Website metrics

See Also:



452
453
454
 
# File 'lib/umami/client.rb', line 452

def website_metrics(id, params = {})
  get("/api/websites/#{id}/metrics", params)
end

#website_pageviews(id, params = {}) ⇒ Hash

Get website pageviews

Parameters:

  • id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date

  • :endAt (Integer) —

    Timestamp (in ms) of end date

  • :unit (String) —

    Time unit (year | month | hour | day)

  • :timezone (String) —

    Timezone (ex. America/Los_Angeles)

  • :url (String) —

    Name of URL

  • :referrer (String) —

    Name of referrer

  • :title (String) —

    Name of page title

  • :os (String) —

    Name of operating system

  • :browser (String) —

    Name of browser

  • :device (String) —

    Name of device

  • :country (String) —

    Name of country

  • :region (String) —

    Name of region/state/province

  • :city (String) —

    Name of city

Returns:

  • (Hash) —

    Website pageviews and sessions

See Also:



426
427
428
 
# File 'lib/umami/client.rb', line 426

def website_pageviews(id, params = {})
  get("/api/websites/#{id}/pageviews", params)
end

#website_stats(id, params = {}) ⇒ Hash

Get website statistics

Parameters:

  • id (String) —

    The website's ID

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :startAt (Integer) —

    Timestamp (in ms) of starting date

  • :endAt (Integer) —

    Timestamp (in ms) of end date

  • :url (String) —

    Name of URL

  • :referrer (String) —

    Name of referrer

  • :title (String) —

    Name of page title

  • :query (String) —

    Name of query

  • :event (String) —

    Name of event

  • :os (String) —

    Name of operating system

  • :browser (String) —

    Name of browser

  • :device (String) —

    Name of device

  • :country (String) —

    Name of country

  • :region (String) —

    Name of region/state/province

  • :city (String) —

    Name of city

Returns:

  • (Hash) —

    Website statistics

See Also:



379
380
381
 
# File 'lib/umami/client.rb', line 379

def website_stats(id, params = {})
  get("/api/websites/#{id}/stats", params)
end

#websites(params = {}) ⇒ Array<Hash>

Get all websites

Parameters:

  • params (Hash) (defaults to: {}) —

    Query parameters

Options Hash (params):

  • :query (String) —

    Search text

  • :page (Integer) —

    Page number

  • :pageSize (Integer) —

    Number of results per page

  • :orderBy (String) —

    Column to order by

Returns:

  • (Array<Hash>) —

    List of websites

See Also:



301
302
303
 
# File 'lib/umami/client.rb', line 301

def websites(params = {})
  get("/api/websites", params)
end