umami-ruby 0.1.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. checksums.yaml +4 -4
  2. data/.env.test +9 -0
  3. data/.simplecov +36 -0
  4. data/CHANGELOG.md +83 -1
  5. data/CLAUDE.md +45 -0
  6. data/README.md +396 -25
  7. data/Rakefile +10 -1
  8. data/docs/Umami/APIError.html +2 -2
  9. data/docs/Umami/AuthenticationError.html +2 -2
  10. data/docs/Umami/Client.html +11047 -1855
  11. data/docs/Umami/ClientError.html +2 -2
  12. data/docs/Umami/Configuration.html +401 -81
  13. data/docs/Umami/ConfigurationError.html +2 -2
  14. data/docs/Umami/Error.html +2 -2
  15. data/docs/Umami/NotFoundError.html +2 -2
  16. data/docs/Umami/ServerError.html +2 -2
  17. data/docs/Umami.html +3 -3
  18. data/docs/_index.html +2 -2
  19. data/docs/file.CHANGELOG.html +117 -3
  20. data/docs/file.LICENSE.html +2 -2
  21. data/docs/file.README.html +465 -30
  22. data/docs/index.html +465 -30
  23. data/docs/method_list.html +395 -19
  24. data/docs/top-level-namespace.html +2 -2
  25. data/lib/umami/client.rb +989 -192
  26. data/lib/umami/configuration.rb +62 -0
  27. data/lib/umami/version.rb +1 -1
  28. metadata +6 -62
data/docs/file.README.html CHANGED
@@ -57,11 +57,16 @@
57
57
  <div class="clear"></div>
58
58
  </div>
59
59
 
60
- <div id="content"><div id='filecontents'><h1 id="umami-ruby">Umami Ruby</h1>
60
+ <div id="content"><div id='filecontents'><h1 id="umami-ruby-ruby-client-for-the-umami-analytics-api">📊 <code>umami-ruby</code> – Ruby client for the Umami Analytics API</h1>
61
61
 
62
- <p><a href="https://badge.fury.io/rb/umami-ruby"><img src="https://badge.fury.io/rb/umami-ruby.svg" alt="Gem Version"></a></p>
62
+ <p><a href="https://badge.fury.io/rb/umami-ruby"><img src="https://badge.fury.io/rb/umami-ruby.svg" alt="Gem Version"></a> <a href="https://github.com/rameerez/umami-ruby/actions"><img src="https://github.com/rameerez/umami-ruby/workflows/Tests/badge.svg" alt="Build Status"></a></p>
63
63
 
64
- <p>A Ruby wrapper for the Umami analytics API.</p>
64
+ <blockquote>
65
+ <p>[!TIP]
66
+ <strong>🚀 Ship your next Rails app 10x faster!</strong> I&#39;ve built <strong><a href="https://railsfast.com/?ref=umami-ruby">RailsFast</a></strong>, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go <a href="https://railsfast.com/?ref=umami-ruby">check it out</a>!</p>
67
+ </blockquote>
68
+
69
+ <p><code>umami-ruby</code> is a comprehensive Ruby wrapper for the <a href="https://umami.is/docs/api">Umami Analytics API</a>. Works with both Umami Cloud and self-hosted instances.</p>
65
70
 
66
71
  <h2 id="installation">Installation</h2>
67
72
 
@@ -88,77 +93,507 @@
88
93
  yard server
89
94
  </code></pre>
90
95
 
91
- <h2 id="usage">Usage</h2>
92
-
93
- <h3 id="configuration">Configuration</h3>
96
+ <h2 id="configuration">Configuration</h2>
94
97
 
95
98
  <p>You can put this config in a handy location within your Rails project, like <code>config/initializers/umami.rb</code></p>
96
99
 
97
- <h4 id="for-self-hosted-umami-instances">For self-hosted Umami instances:</h4>
100
+ <h3 id="for-umami-cloud">For Umami Cloud</h3>
101
+
102
+ <pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Umami.html#configure-class_method" title="Umami.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
103
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_access_token'>access_token</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your_api_key</span><span class='tstring_end'>&quot;</span></span>
104
+ <span class='comment'># No need to specify uri_base - automatically uses https://api.umami.is
105
+ </span><span class='kw'>end</span>
106
+ </code></pre>
98
107
 
99
- <pre class="code ruby"><code class="ruby"><span class='comment'># With username and password
108
+ <h3 id="for-self-hosted-umami-instances">For Self-Hosted Umami Instances</h3>
109
+
110
+ <pre class="code ruby"><code class="ruby"><span class='comment'># With an access token
100
111
  </span><span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Umami.html#configure-class_method" title="Umami.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
101
112
  <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_uri_base'>uri_base</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>https://your-umami-instance.com</span><span class='tstring_end'>&quot;</span></span>
102
- <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_credentials'>credentials</span> <span class='op'>=</span> <span class='lbrace'>{</span>
103
- <span class='label'>username:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your_username</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
104
- <span class='label'>password:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your_password</span><span class='tstring_end'>&quot;</span></span>
105
- <span class='rbrace'>}</span>
113
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_access_token'>access_token</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your_access_token</span><span class='tstring_end'>&quot;</span></span>
106
114
  <span class='kw'>end</span>
107
115
 
108
- <span class='comment'># Or with an access token
116
+ <span class='comment'># Or with username and password
109
117
  </span><span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Umami.html#configure-class_method" title="Umami.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
110
118
  <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_uri_base'>uri_base</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>https://your-umami-instance.com</span><span class='tstring_end'>&quot;</span></span>
111
- <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_access_token'>access_token</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your_access_token</span><span class='tstring_end'>&quot;</span></span>
119
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_credentials'>credentials</span> <span class='op'>=</span> <span class='lbrace'>{</span>
120
+ <span class='label'>username:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your_username</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
121
+ <span class='label'>password:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your_password</span><span class='tstring_end'>&quot;</span></span>
122
+ <span class='rbrace'>}</span>
112
123
  <span class='kw'>end</span>
113
124
  </code></pre>
114
125
 
115
- <h4 id="for-umami-cloud">For Umami Cloud:</h4>
116
-
117
- <pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Umami.html#configure-class_method" title="Umami.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
126
+ <h3 id="configuration-options">Configuration Options</h3>
127
+
128
+ <table><thead>
129
+ <tr>
130
+ <th>Option</th>
131
+ <th>Description</th>
132
+ <th>Default</th>
133
+ </tr>
134
+ </thead><tbody>
135
+ <tr>
136
+ <td><code>access_token</code></td>
137
+ <td>API key for Umami Cloud or access token for self-hosted</td>
138
+ <td><code>nil</code></td>
139
+ </tr>
140
+ <tr>
141
+ <td><code>uri_base</code></td>
142
+ <td>Base URL for self-hosted instances</td>
143
+ <td>Auto-detected</td>
144
+ </tr>
145
+ <tr>
146
+ <td><code>credentials</code></td>
147
+ <td>Hash with <code>:username</code> and <code>:password</code> for self-hosted</td>
148
+ <td><code>nil</code></td>
149
+ </tr>
150
+ <tr>
151
+ <td><code>request_timeout</code></td>
152
+ <td>Request timeout in seconds</td>
153
+ <td><code>120</code></td>
154
+ </tr>
155
+ </tbody></table>
156
+
157
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Example with custom timeout
158
+ </span><span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='period'>.</span><span class='id identifier rubyid_configure'><span class='object_link'><a href="Umami.html#configure-class_method" title="Umami.configure (method)">configure</a></span></span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_config'>config</span><span class='op'>|</span>
118
159
  <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_access_token'>access_token</span> <span class='op'>=</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your_api_key</span><span class='tstring_end'>&quot;</span></span>
119
- <span class='comment'># No need to specify uri_base for Umami Cloud
160
+ <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_request_timeout'>request_timeout</span> <span class='op'>=</span> <span class='int'>60</span> <span class='comment'># 60 seconds
120
161
  </span><span class='kw'>end</span>
121
162
  </code></pre>
122
163
 
123
- <h3 id="using-the-client">Using the Client</h3>
164
+ <h2 id="usage">Usage</h2>
124
165
 
125
- <p>After configuration, you can use the client to interact with the Umami API:</p>
166
+ <h3 id="basic-usage">Basic Usage</h3>
126
167
 
127
168
  <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Umami/Client.html" title="Umami::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Umami/Client.html#initialize-instance_method" title="Umami::Client#initialize (method)">new</a></span></span>
128
169
 
170
+ <span class='comment'># Get current user info
171
+ </span><span class='id identifier rubyid_me'>me</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_me'>me</span>
172
+
129
173
  <span class='comment'># Get all websites
130
174
  </span><span class='id identifier rubyid_websites'>websites</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_websites'>websites</span>
131
175
 
132
176
  <span class='comment'># Get a specific website
133
177
  </span><span class='id identifier rubyid_website'>website</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website'>website</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
134
178
 
135
- <span class='comment'># Get website stats
136
- </span><span class='id identifier rubyid_stats'>stats</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_stats'>website_stats</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span> <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span> <span class='label'>endAt:</span> <span class='int'>1656766119687</span> <span class='rbrace'>}</span><span class='rparen'>)</span>
137
-
138
179
  <span class='comment'># Verify token
139
180
  </span><span class='id identifier rubyid_token_info'>token_info</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_verify_token'>verify_token</span>
140
181
  </code></pre>
141
182
 
183
+ <h3 id="website-statistics">Website Statistics</h3>
184
+
185
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Get website stats for a time range (timestamps in milliseconds)
186
+ </span><span class='id identifier rubyid_stats'>stats</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_stats'>website_stats</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
187
+ <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span>
188
+ <span class='label'>endAt:</span> <span class='int'>1656766119687</span>
189
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
190
+
191
+ <span class='comment'># Get active visitors (last 5 minutes)
192
+ </span><span class='id identifier rubyid_active'>active</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_active_visitors'>website_active_visitors</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
193
+
194
+ <span class='comment'># Get pageviews with time grouping
195
+ </span><span class='id identifier rubyid_pageviews'>pageviews</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_pageviews'>website_pageviews</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
196
+ <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span>
197
+ <span class='label'>endAt:</span> <span class='int'>1656766119687</span><span class='comma'>,</span>
198
+ <span class='label'>unit:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>day</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
199
+ <span class='label'>timezone:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>America/Los_Angeles</span><span class='tstring_end'>&quot;</span></span>
200
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
201
+
202
+ <span class='comment'># Get metrics by type
203
+ </span><span class='id identifier rubyid_metrics'>metrics</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_metrics'>website_metrics</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
204
+ <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span>
205
+ <span class='label'>endAt:</span> <span class='int'>1656766119687</span><span class='comma'>,</span>
206
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>browser</span><span class='tstring_end'>&quot;</span></span> <span class='comment'># or: path, referrer, os, device, country, etc.
207
+ </span><span class='rbrace'>}</span><span class='rparen'>)</span>
208
+
209
+ <span class='comment'># Get realtime stats (last 30 minutes)
210
+ </span><span class='id identifier rubyid_realtime'>realtime</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_realtime'>realtime</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
211
+ </code></pre>
212
+
213
+ <h3 id="sending-events">Sending Events</h3>
214
+
215
+ <p>Send custom events to Umami for tracking. This is useful for server-side event tracking.</p>
216
+
217
+ <pre class="code ruby"><code class="ruby"><span class='id identifier rubyid_client'>client</span> <span class='op'>=</span> <span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Umami/Client.html" title="Umami::Client (class)">Client</a></span></span><span class='period'>.</span><span class='id identifier rubyid_new'><span class='object_link'><a href="Umami/Client.html#initialize-instance_method" title="Umami::Client#initialize (method)">new</a></span></span>
218
+
219
+ <span class='comment'># Send a basic event
220
+ </span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_send_event'>send_event</span><span class='lparen'>(</span><span class='lbrace'>{</span>
221
+ <span class='label'>website:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your-website-id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
222
+ <span class='label'>url:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>/checkout</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
223
+ <span class='label'>hostname:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>example.com</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
224
+ <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>purchase_completed</span><span class='tstring_end'>&quot;</span></span>
225
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
226
+
227
+ <span class='comment'># Send an event with custom data
228
+ </span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_send_event'>send_event</span><span class='lparen'>(</span><span class='lbrace'>{</span>
229
+ <span class='label'>website:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>your-website-id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
230
+ <span class='label'>url:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>/checkout</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
231
+ <span class='label'>hostname:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>example.com</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
232
+ <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>purchase_completed</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
233
+ <span class='label'>language:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>en-US</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
234
+ <span class='label'>screen:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>1920x1080</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
235
+ <span class='label'>title:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Checkout - Example Store</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
236
+ <span class='label'>data:</span> <span class='lbrace'>{</span>
237
+ <span class='label'>order_id:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>12345</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
238
+ <span class='label'>total:</span> <span class='float'>99.99</span><span class='comma'>,</span>
239
+ <span class='label'>currency:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>USD</span><span class='tstring_end'>&quot;</span></span>
240
+ <span class='rbrace'>}</span>
241
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
242
+
243
+ <span class='comment'># Send with a custom User-Agent (optional)
244
+ </span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_send_event'>send_event</span><span class='lparen'>(</span><span class='id identifier rubyid_payload'>payload</span><span class='comma'>,</span> <span class='label'>user_agent:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>MyApp/1.0</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
245
+ </code></pre>
246
+
247
+ <p><strong>Important notes about <code>send_event</code>:</strong></p>
248
+
249
+ <ul>
250
+ <li>No authentication token is sent (not required by the API)</li>
251
+ <li>A <code>User-Agent</code> header is automatically included (required by Umami)</li>
252
+ <li>For Umami Cloud, requests go to <code>https://cloud.umami.is/api/send</code> (different from other API calls)</li>
253
+ <li>For self-hosted, requests go to your configured <code>uri_base</code></li>
254
+ </ul>
255
+
256
+ <h3 id="sessions">Sessions</h3>
257
+
258
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Get sessions within a time range
259
+ </span><span class='id identifier rubyid_sessions'>sessions</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_sessions'>website_sessions</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
260
+ <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span>
261
+ <span class='label'>endAt:</span> <span class='int'>1656766119687</span><span class='comma'>,</span>
262
+ <span class='label'>page:</span> <span class='int'>1</span><span class='comma'>,</span>
263
+ <span class='label'>pageSize:</span> <span class='int'>20</span>
264
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
265
+
266
+ <span class='comment'># Get session statistics
267
+ </span><span class='id identifier rubyid_stats'>stats</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_sessions_stats'>website_sessions_stats</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
268
+ <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span>
269
+ <span class='label'>endAt:</span> <span class='int'>1656766119687</span>
270
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
271
+
272
+ <span class='comment'># Get individual session details
273
+ </span><span class='id identifier rubyid_session'>session</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_session'>website_session</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>session_id</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
274
+
275
+ <span class='comment'># Get session activity
276
+ </span><span class='id identifier rubyid_activity'>activity</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_session_activity'>website_session_activity</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>session_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
277
+ <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span>
278
+ <span class='label'>endAt:</span> <span class='int'>1656766119687</span>
279
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
280
+ </code></pre>
281
+
282
+ <h3 id="events-data">Events Data</h3>
283
+
284
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Get paginated event list with search
285
+ </span><span class='id identifier rubyid_events'>events</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_events_list'>website_events_list</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
286
+ <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span>
287
+ <span class='label'>endAt:</span> <span class='int'>1656766119687</span><span class='comma'>,</span>
288
+ <span class='label'>search:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>click</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
289
+ <span class='label'>page:</span> <span class='int'>1</span><span class='comma'>,</span>
290
+ <span class='label'>pageSize:</span> <span class='int'>20</span>
291
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
292
+
293
+ <span class='comment'># Get event data aggregations
294
+ </span><span class='id identifier rubyid_event_data'>event_data</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_event_data_events'>website_event_data_events</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
295
+ <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span>
296
+ <span class='label'>endAt:</span> <span class='int'>1656766119687</span>
297
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
298
+
299
+ <span class='comment'># Get event statistics
300
+ </span><span class='id identifier rubyid_stats'>stats</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website_event_data_stats'>website_event_data_stats</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
301
+ <span class='label'>startAt:</span> <span class='int'>1656679719687</span><span class='comma'>,</span>
302
+ <span class='label'>endAt:</span> <span class='int'>1656766119687</span>
303
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
304
+ </code></pre>
305
+
306
+ <h3 id="reports">Reports</h3>
307
+
308
+ <pre class="code ruby"><code class="ruby"><span class='comment'># List reports (optionally filter by website and/or type)
309
+ </span><span class='id identifier rubyid_all_reports'>all_reports</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_reports'>reports</span>
310
+ <span class='id identifier rubyid_website_reports'>website_reports</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_reports'>reports</span><span class='lparen'>(</span><span class='label'>websiteId:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
311
+ <span class='id identifier rubyid_funnel_reports'>funnel_reports</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_reports'>reports</span><span class='lparen'>(</span><span class='label'>websiteId:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>funnel</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
312
+
313
+ <span class='comment'># Create a report
314
+ </span><span class='id identifier rubyid_report'>report</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_create_report'>create_report</span><span class='lparen'>(</span><span class='lbrace'>{</span>
315
+ <span class='label'>websiteId:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
316
+ <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>funnel</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
317
+ <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Checkout Funnel</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
318
+ <span class='label'>parameters:</span> <span class='lbrace'>{</span>
319
+ <span class='label'>startDate:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>2024-01-01T00:00:00Z</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
320
+ <span class='label'>endDate:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>2024-01-31T23:59:59Z</span><span class='tstring_end'>&quot;</span></span>
321
+ <span class='rbrace'>}</span>
322
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
323
+
324
+ <span class='comment'># Run specialized reports
325
+ </span><span class='id identifier rubyid_funnel'>funnel</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_report_funnel'>report_funnel</span><span class='lparen'>(</span><span class='lbrace'>{</span>
326
+ <span class='label'>websiteId:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
327
+ <span class='label'>startDate:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>2024-01-01T00:00:00Z</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
328
+ <span class='label'>endDate:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>2024-01-31T23:59:59Z</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
329
+ <span class='label'>steps:</span> <span class='lbracket'>[</span>
330
+ <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>path</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>value:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>/</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
331
+ <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>path</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>value:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>/checkout</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span><span class='comma'>,</span>
332
+ <span class='lbrace'>{</span> <span class='label'>type:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>path</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='label'>value:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>/thank-you</span><span class='tstring_end'>&quot;</span></span> <span class='rbrace'>}</span>
333
+ <span class='rbracket'>]</span><span class='comma'>,</span>
334
+ <span class='label'>window:</span> <span class='int'>7</span>
335
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
336
+
337
+ <span class='id identifier rubyid_retention'>retention</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_report_retention'>report_retention</span><span class='lparen'>(</span><span class='lbrace'>{</span>
338
+ <span class='label'>websiteId:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
339
+ <span class='label'>startDate:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>2024-01-01T00:00:00Z</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
340
+ <span class='label'>endDate:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>2024-01-31T23:59:59Z</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
341
+ <span class='label'>timezone:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>America/Los_Angeles</span><span class='tstring_end'>&quot;</span></span>
342
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
343
+
344
+ <span class='comment'># Available report types: attribution, breakdown, funnel, goal, journey, retention, revenue, utm
345
+ </span></code></pre>
346
+
347
+ <p><strong>Report types:</strong>
348
+ | Type | Description |
349
+ |------|-------------|
350
+ | <code>attribution</code> | Marketing channel attribution analysis |
351
+ | <code>breakdown</code> | Multi-dimensional data segmentation |
352
+ | <code>funnel</code> | Conversion funnel tracking |
353
+ | <code>goal</code> | Goal performance metrics |
354
+ | <code>journey</code> | User navigation path analysis |
355
+ | <code>retention</code> | Return visitor analysis |
356
+ | <code>revenue</code> | Revenue tracking and analysis |
357
+ | <code>utm</code> | UTM campaign parameter breakdown |</p>
358
+
359
+ <h3 id="user-team-management">User &amp; Team Management</h3>
360
+
361
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Get current user info
362
+ </span><span class='id identifier rubyid_me'>me</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_me'>me</span>
363
+ <span class='id identifier rubyid_my_teams'>my_teams</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_my_teams'>my_teams</span><span class='lparen'>(</span><span class='label'>page:</span> <span class='int'>1</span><span class='comma'>,</span> <span class='label'>pageSize:</span> <span class='int'>10</span><span class='rparen'>)</span>
364
+ <span class='id identifier rubyid_my_websites'>my_websites</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_my_websites'>my_websites</span><span class='lparen'>(</span><span class='label'>includeTeams:</span> <span class='kw'>true</span><span class='rparen'>)</span>
365
+
366
+ <span class='comment'># Team management
367
+ </span><span class='id identifier rubyid_teams'>teams</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_teams'>teams</span>
368
+ <span class='id identifier rubyid_team'>team</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_team'>team</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>team_id</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
369
+ <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_create_team'>create_team</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>My Team</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
370
+ <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_add_team_user'>add_team_user</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>team_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>user_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>team-member</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
371
+
372
+ <span class='comment'># User management (admin only, self-hosted)
373
+ </span><span class='id identifier rubyid_users'>users</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_admin_users'>admin_users</span>
374
+ <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_create_user'>create_user</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>username</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>password</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>user</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
375
+ </code></pre>
376
+
377
+ <h3 id="website-management">Website Management</h3>
378
+
379
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Create a website
380
+ </span><span class='id identifier rubyid_website'>website</span> <span class='op'>=</span> <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_create_website'>create_website</span><span class='lparen'>(</span><span class='lbrace'>{</span>
381
+ <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>My Website</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
382
+ <span class='label'>domain:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>example.com</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
383
+ <span class='label'>teamId:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>optional-team-id</span><span class='tstring_end'>&quot;</span></span>
384
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
385
+
386
+ <span class='comment'># Update a website
387
+ </span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_update_website'>update_website</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='lbrace'>{</span>
388
+ <span class='label'>name:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Updated Name</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span>
389
+ <span class='label'>shareId:</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>public-share-id</span><span class='tstring_end'>&quot;</span></span>
390
+ <span class='rbrace'>}</span><span class='rparen'>)</span>
391
+
392
+ <span class='comment'># Reset website data
393
+ </span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_reset_website'>reset_website</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
394
+
395
+ <span class='comment'># Delete a website
396
+ </span><span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_delete_website'>delete_website</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>website_id</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
397
+ </code></pre>
398
+
399
+ <h2 id="available-methods">Available Methods</h2>
400
+
401
+ <h3 id="authentication">Authentication</h3>
402
+
403
+ <ul>
404
+ <li><code>verify_token</code> - Verify the current authentication token</li>
405
+ </ul>
406
+
407
+ <h3 id="me-current-user">Me (Current User)</h3>
408
+
409
+ <ul>
410
+ <li><code>me</code> - Get current user information</li>
411
+ <li><code>my_teams(params)</code> - Get user&#39;s teams (supports pagination)</li>
412
+ <li><code>my_websites(params)</code> - Get user&#39;s websites</li>
413
+ </ul>
414
+
415
+ <h3 id="admin-self-hosted-only">Admin (Self-hosted only)</h3>
416
+
417
+ <ul>
418
+ <li><code>admin_users(params)</code> - List all users</li>
419
+ <li><code>admin_websites(params)</code> - List all websites</li>
420
+ <li><code>admin_teams(params)</code> - List all teams</li>
421
+ </ul>
422
+
423
+ <h3 id="users">Users</h3>
424
+
425
+ <ul>
426
+ <li><code>create_user(username, password, role, id:)</code> - Create a user</li>
427
+ <li><code>user(user_id)</code> - Get user by ID</li>
428
+ <li><code>update_user(user_id, params)</code> - Update user</li>
429
+ <li><code>delete_user(user_id)</code> - Delete user</li>
430
+ <li><code>user_websites(user_id, params)</code> - Get user&#39;s websites</li>
431
+ <li><code>user_teams(user_id, params)</code> - Get user&#39;s teams</li>
432
+ </ul>
433
+
434
+ <h3 id="teams">Teams</h3>
435
+
436
+ <ul>
437
+ <li><code>teams(params)</code> - List all teams</li>
438
+ <li><code>create_team(name)</code> - Create a team</li>
439
+ <li><code>join_team(access_code)</code> - Join a team</li>
440
+ <li><code>team(team_id)</code> - Get team by ID</li>
441
+ <li><code>update_team(team_id, params)</code> - Update team</li>
442
+ <li><code>delete_team(team_id)</code> - Delete team</li>
443
+ <li><code>team_users(team_id, params)</code> - List team members</li>
444
+ <li><code>add_team_user(team_id, user_id, role)</code> - Add user to team</li>
445
+ <li><code>team_user(team_id, user_id)</code> - Get team member</li>
446
+ <li><code>update_team_user(team_id, user_id, role)</code> - Update member role</li>
447
+ <li><code>delete_team_user(team_id, user_id)</code> - Remove user from team</li>
448
+ <li><code>team_websites(team_id, params)</code> - List team websites</li>
449
+ </ul>
450
+
451
+ <h3 id="websites">Websites</h3>
452
+
453
+ <ul>
454
+ <li><code>websites(params)</code> - List all websites</li>
455
+ <li><code>create_website(params)</code> - Create a website</li>
456
+ <li><code>website(website_id)</code> - Get website by ID</li>
457
+ <li><code>update_website(website_id, params)</code> - Update website</li>
458
+ <li><code>delete_website(website_id)</code> - Delete website</li>
459
+ <li><code>reset_website(website_id)</code> - Reset website data</li>
460
+ </ul>
461
+
462
+ <h3 id="website-statistics">Website Statistics</h3>
463
+
464
+ <ul>
465
+ <li><code>website_stats(website_id, params)</code> - Get statistics</li>
466
+ <li><code>website_active_visitors(website_id)</code> - Get active visitors</li>
467
+ <li><code>website_pageviews(website_id, params)</code> - Get pageviews</li>
468
+ <li><code>website_events(website_id, params)</code> - Get events (time-series)</li>
469
+ <li><code>website_events_series(website_id, params)</code> - Get events series</li>
470
+ <li><code>website_metrics(website_id, params)</code> - Get metrics</li>
471
+ <li><code>website_metrics_expanded(website_id, params)</code> - Get expanded metrics</li>
472
+ </ul>
473
+
474
+ <h3 id="sessions">Sessions</h3>
475
+
476
+ <ul>
477
+ <li><code>website_sessions(website_id, params)</code> - List sessions</li>
478
+ <li><code>website_sessions_stats(website_id, params)</code> - Get session stats</li>
479
+ <li><code>website_sessions_weekly(website_id, params)</code> - Get weekly breakdown</li>
480
+ <li><code>website_session(website_id, session_id)</code> - Get session details</li>
481
+ <li><code>website_session_activity(website_id, session_id, params)</code> - Get activity</li>
482
+ <li><code>website_session_properties(website_id, session_id)</code> - Get properties</li>
483
+ <li><code>website_session_data_properties(website_id, params)</code> - Get data properties</li>
484
+ <li><code>website_session_data_values(website_id, params)</code> - Get data values</li>
485
+ </ul>
486
+
487
+ <h3 id="events">Events</h3>
488
+
489
+ <ul>
490
+ <li><code>website_events_list(website_id, params)</code> - List events (paginated)</li>
491
+ <li><code>website_event_data(website_id, event_id)</code> - Get event data</li>
492
+ <li><code>website_event_data_events(website_id, params)</code> - Get event aggregations</li>
493
+ <li><code>website_event_data_fields(website_id, params)</code> - Get event fields</li>
494
+ <li><code>website_event_data_properties(website_id, params)</code> - Get event properties</li>
495
+ <li><code>website_event_data_values(website_id, params)</code> - Get event values</li>
496
+ <li><code>website_event_data_stats(website_id, params)</code> - Get event statistics</li>
497
+ </ul>
498
+
499
+ <h3 id="realtime">Realtime</h3>
500
+
501
+ <ul>
502
+ <li><code>realtime(website_id)</code> - Get realtime stats (last 30 minutes)</li>
503
+ </ul>
504
+
505
+ <h3 id="links">Links</h3>
506
+
507
+ <ul>
508
+ <li><code>links(params)</code> - List all links</li>
509
+ <li><code>link(link_id)</code> - Get link by ID</li>
510
+ <li><code>update_link(link_id, params)</code> - Update link</li>
511
+ <li><code>delete_link(link_id)</code> - Delete link</li>
512
+ </ul>
513
+
514
+ <h3 id="pixels">Pixels</h3>
515
+
516
+ <ul>
517
+ <li><code>pixels(params)</code> - List all pixels</li>
518
+ <li><code>pixel(pixel_id)</code> - Get pixel by ID</li>
519
+ <li><code>update_pixel(pixel_id, params)</code> - Update pixel</li>
520
+ <li><code>delete_pixel(pixel_id)</code> - Delete pixel</li>
521
+ </ul>
522
+
523
+ <h3 id="reports">Reports</h3>
524
+
525
+ <ul>
526
+ <li><code>reports(params)</code> - List all reports (filter by <code>websiteId</code>, <code>type</code>)</li>
527
+ <li><code>create_report(params)</code> - Create a report</li>
528
+ <li><code>report(report_id)</code> - Get report by ID</li>
529
+ <li><code>update_report(report_id, params)</code> - Update report</li>
530
+ <li><code>delete_report(report_id)</code> - Delete report</li>
531
+ <li><code>report_attribution(params)</code> - Run attribution report</li>
532
+ <li><code>report_breakdown(params)</code> - Run breakdown report</li>
533
+ <li><code>report_funnel(params)</code> - Run funnel report</li>
534
+ <li><code>report_goals(params)</code> - Run goals report</li>
535
+ <li><code>report_journey(params)</code> - Run journey report</li>
536
+ <li><code>report_retention(params)</code> - Run retention report</li>
537
+ <li><code>report_revenue(params)</code> - Run revenue report</li>
538
+ <li><code>report_utm(params)</code> - Run UTM report</li>
539
+ </ul>
540
+
541
+ <h3 id="sending-events">Sending Events</h3>
542
+
543
+ <ul>
544
+ <li><code>send_event(payload, user_agent:)</code> - Send tracking event</li>
545
+ </ul>
546
+
142
547
  <h2 id="error-handling">Error Handling</h2>
143
548
 
144
549
  <p>The gem defines several custom error classes:</p>
145
550
 
551
+ <pre class="code ruby"><code class="ruby"><span class='kw'>begin</span>
552
+ <span class='id identifier rubyid_client'>client</span><span class='period'>.</span><span class='id identifier rubyid_website'>website</span><span class='lparen'>(</span><span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>non-existent-id</span><span class='tstring_end'>&quot;</span></span><span class='rparen'>)</span>
553
+ <span class='kw'>rescue</span> <span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Umami/NotFoundError.html" title="Umami::NotFoundError (class)">NotFoundError</a></span></span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_e'>e</span>
554
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Website not found: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_message'>message</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
555
+ <span class='kw'>rescue</span> <span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Umami/ClientError.html" title="Umami::ClientError (class)">ClientError</a></span></span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_e'>e</span>
556
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Client error: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_message'>message</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
557
+ <span class='kw'>rescue</span> <span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Umami/ServerError.html" title="Umami::ServerError (class)">ServerError</a></span></span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_e'>e</span>
558
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Server error: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_message'>message</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
559
+ <span class='kw'>rescue</span> <span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Umami/AuthenticationError.html" title="Umami::AuthenticationError (class)">AuthenticationError</a></span></span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_e'>e</span>
560
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Authentication failed: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_message'>message</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
561
+ <span class='kw'>rescue</span> <span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Umami/ConfigurationError.html" title="Umami::ConfigurationError (class)">ConfigurationError</a></span></span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_e'>e</span>
562
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>Configuration error: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_message'>message</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
563
+ <span class='kw'>rescue</span> <span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='op'>::</span><span class='const'><span class='object_link'><a href="Umami/APIError.html" title="Umami::APIError (class)">APIError</a></span></span> <span class='op'>=&gt;</span> <span class='id identifier rubyid_e'>e</span>
564
+ <span class='id identifier rubyid_puts'>puts</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>API error: </span><span class='embexpr_beg'>#{</span><span class='id identifier rubyid_e'>e</span><span class='period'>.</span><span class='id identifier rubyid_message'>message</span><span class='embexpr_end'>}</span><span class='tstring_end'>&quot;</span></span>
565
+ <span class='kw'>end</span>
566
+ </code></pre>
567
+
568
+ <p><strong>Error class hierarchy:</strong></p>
569
+
146
570
  <ul>
147
- <li><code>Umami::ConfigurationError</code>: Raised for configuration-related issues.</li>
148
- <li><code>Umami::AuthenticationError</code>: Raised for authentication-related issues.</li>
149
- <li><code>Umami::APIError</code>: Raised for API request failures.</li>
571
+ <li><code>Umami::Error</code> - Base error class
572
+
573
+ <ul>
574
+ <li><code>Umami::ConfigurationError</code> - Configuration issues</li>
575
+ <li><code>Umami::AuthenticationError</code> - Authentication failures</li>
576
+ <li><code>Umami::APIError</code> - API request failures</li>
577
+ <li><code>Umami::NotFoundError</code> - Resource not found (404)</li>
578
+ <li><code>Umami::ClientError</code> - Client errors (4xx)</li>
579
+ <li><code>Umami::ServerError</code> - Server errors (5xx)</li>
580
+ </ul></li>
150
581
  </ul>
151
582
 
152
583
  <h2 id="logging">Logging</h2>
153
584
 
154
585
  <p>The gem uses a logger that can be configured:</p>
155
586
 
156
- <pre class="code ruby"><code class="ruby"><span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='period'>.</span><span class='id identifier rubyid_logger'><span class='object_link'><a href="Umami.html#logger-class_method" title="Umami.logger (method)">logger</a></span></span><span class='period'>.</span><span class='id identifier rubyid_level'>level</span> <span class='op'>=</span> <span class='const'>Logger</span><span class='op'>::</span><span class='const'>DEBUG</span>
587
+ <pre class="code ruby"><code class="ruby"><span class='comment'># Set log level
588
+ </span><span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='period'>.</span><span class='id identifier rubyid_logger'><span class='object_link'><a href="Umami.html#logger-class_method" title="Umami.logger (method)">logger</a></span></span><span class='period'>.</span><span class='id identifier rubyid_level'>level</span> <span class='op'>=</span> <span class='const'>Logger</span><span class='op'>::</span><span class='const'>DEBUG</span>
589
+
590
+ <span class='comment'># Use a custom logger
591
+ </span><span class='const'><span class='object_link'><a href="Umami.html" title="Umami (module)">Umami</a></span></span><span class='period'>.</span><span class='id identifier rubyid_logger'><span class='object_link'><a href="Umami.html#logger-class_method" title="Umami.logger (method)">logger</a></span></span> <span class='op'>=</span> <span class='const'>Rails</span><span class='period'>.</span><span class='id identifier rubyid_logger'>logger</span>
157
592
  </code></pre>
158
593
 
159
594
  <h2 id="development">Development</h2>
160
595
 
161
- <p>After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run <code>rake spec</code> to run the tests. You can also run <code>bin/console</code> for an interactive prompt that will allow you to experiment.</p>
596
+ <p>After checking out the repo, run <code>bin/setup</code> to install dependencies. Then, run <code>bundle exec rake test</code> to run the tests. You can also run <code>bin/console</code> for an interactive prompt that will allow you to experiment.</p>
162
597
 
163
598
  <p>To install this gem onto your local machine, run <code>bundle exec rake install</code>.</p>
164
599
 
@@ -172,9 +607,9 @@ yard server
172
607
  </div></div>
173
608
 
174
609
  <div id="footer">
175
- Generated on Mon Jul 22 17:42:41 2024 by
610
+ Generated on Tue Feb 3 01:30:16 2026 by
176
611
  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
177
- 0.9.36 (ruby-3.2.2).
612
+ 0.9.36 (ruby-3.4.2).
178
613
  </div>
179
614
 
180
615
  </div>