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
31
32
 
# File 'lib/umami/client.rb', line 19

def initialize(options = {})
  @config = options[:config] || Umami.configuration
  @config.validate!  # Validate the configuration before using it

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



243
244
245
 
# File 'lib/umami/client.rb', line 243

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



37
38
39
 
# File 'lib/umami/client.rb', line 37

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:



166
167
168
 
# File 'lib/umami/client.rb', line 166

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:



88
89
90
 
# File 'lib/umami/client.rb', line 88

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:



316
317
318
 
# File 'lib/umami/client.rb', line 316

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:



218
219
220
 
# File 'lib/umami/client.rb', line 218

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:



274
275
276
 
# File 'lib/umami/client.rb', line 274

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:



127
128
129
 
# File 'lib/umami/client.rb', line 127

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:



347
348
349
 
# File 'lib/umami/client.rb', line 347

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:



467
468
469
 
# File 'lib/umami/client.rb', line 467

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:



482
483
484
 
# File 'lib/umami/client.rb', line 482

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:



494
495
496
 
# File 'lib/umami/client.rb', line 494

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:



188
189
190
 
# File 'lib/umami/client.rb', line 188

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:



356
357
358
 
# File 'lib/umami/client.rb', line 356

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



44
45
46
 
# File 'lib/umami/client.rb', line 44

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:



514
515
516
 
# File 'lib/umami/client.rb', line 514

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:



197
198
199
 
# File 'lib/umami/client.rb', line 197

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:



253
254
255
 
# File 'lib/umami/client.rb', line 253

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:



232
233
234
 
# File 'lib/umami/client.rb', line 232

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:



288
289
290
 
# File 'lib/umami/client.rb', line 288

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:



179
180
181
 
# File 'lib/umami/client.rb', line 179

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:



209
210
211
 
# File 'lib/umami/client.rb', line 209

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:



264
265
266
 
# File 'lib/umami/client.rb', line 264

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:



118
119
120
 
# File 'lib/umami/client.rb', line 118

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:



338
339
340
 
# File 'lib/umami/client.rb', line 338

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:



105
106
107
 
# File 'lib/umami/client.rb', line 105

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:



155
156
157
 
# File 'lib/umami/client.rb', line 155

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:



141
142
143
 
# File 'lib/umami/client.rb', line 141

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:



96
97
98
 
# File 'lib/umami/client.rb', line 96

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

#verify_token ⇒ Hash

Verify the authentication token

Returns:

  • (Hash) —

    Token verification result

See Also:



52
53
54
 
# File 'lib/umami/client.rb', line 52

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:



325
326
327
 
# File 'lib/umami/client.rb', line 325

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:



390
391
392
 
# File 'lib/umami/client.rb', line 390

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:



405
406
407
 
# File 'lib/umami/client.rb', line 405

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:



454
455
456
 
# File 'lib/umami/client.rb', line 454

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:



428
429
430
 
# File 'lib/umami/client.rb', line 428

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:



381
382
383
 
# File 'lib/umami/client.rb', line 381

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:



303
304
305
 
# File 'lib/umami/client.rb', line 303

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