activitysmith 1.10.0 → 1.12.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 (30) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +273 -254
  3. data/generated/activitysmith_openapi/api/live_activities_api.rb +10 -10
  4. data/generated/activitysmith_openapi/api/metrics_api.rb +2 -2
  5. data/generated/activitysmith_openapi/configuration.rb +7 -0
  6. data/generated/activitysmith_openapi/models/app_icon_badge_count_update_error.rb +386 -0
  7. data/generated/activitysmith_openapi/models/app_icon_badge_count_update_response.rb +33 -11
  8. data/generated/activitysmith_openapi/models/content_state_end.rb +8 -8
  9. data/generated/activitysmith_openapi/models/content_state_start.rb +8 -8
  10. data/generated/activitysmith_openapi/models/content_state_update.rb +8 -8
  11. data/generated/activitysmith_openapi/models/live_activity_action.rb +23 -1
  12. data/generated/activitysmith_openapi/models/live_activity_end_request.rb +64 -2
  13. data/generated/activitysmith_openapi/models/live_activity_limit_error.rb +25 -5
  14. data/generated/activitysmith_openapi/models/live_activity_start_request.rb +33 -2
  15. data/generated/activitysmith_openapi/models/live_activity_stream_delete_request.rb +45 -2
  16. data/generated/activitysmith_openapi/models/live_activity_stream_request.rb +33 -2
  17. data/generated/activitysmith_openapi/models/live_activity_update_request.rb +64 -2
  18. data/generated/activitysmith_openapi/models/live_activity_value.rb +106 -0
  19. data/generated/activitysmith_openapi/models/metadata_value.rb +106 -0
  20. data/generated/activitysmith_openapi/models/push_notification_action.rb +23 -1
  21. data/generated/activitysmith_openapi/models/push_notification_request.rb +45 -5
  22. data/generated/activitysmith_openapi/models/rate_limit_error.rb +44 -1
  23. data/generated/activitysmith_openapi/models/stream_content_state.rb +8 -8
  24. data/generated/activitysmith_openapi/models/update_app_icon_badge_count422_response.rb +105 -0
  25. data/generated/activitysmith_openapi/version.rb +1 -1
  26. data/generated/activitysmith_openapi.rb +4 -0
  27. data/generated/openapi-source.json +6 -0
  28. data/lib/activitysmith/live_activities.rb +7 -6
  29. data/lib/activitysmith/version.rb +1 -1
  30. metadata +7 -2
data/README.md CHANGED
@@ -1,51 +1,35 @@
1
1
  # ActivitySmith Ruby SDK
2
2
 
3
- The ActivitySmith Ruby SDK provides convenient access to the ActivitySmith API from Ruby applications.
4
-
5
- ## Documentation
6
-
7
- See [API reference](https://activitysmith.com/docs/api-reference/introduction).
8
-
9
- ## Table of Contents
10
-
11
- - [Installation](#installation)
12
- - [Setup](#setup)
13
- - [Push Notifications](#push-notifications)
14
- - [Send a Push Notification](#send-a-push-notification)
15
- - [Rich Push Notifications with Media](#rich-push-notifications-with-media)
16
- - [Actionable Push Notifications](#actionable-push-notifications)
17
- - [Live Activities](#live-activities)
18
- - [Start & Update Live Activity](#start--update-live-activity)
19
- - [End Live Activity](#end-live-activity)
20
- - [Live Activity Action](#live-activity-action)
21
- - [Icons and Badges](#icons-and-badges)
22
- - [Live Activity Colors](#live-activity-colors)
23
- - [Widgets](#widgets)
24
- - [App Icon Badge Count](#app-icon-badge-count)
25
- - [Channels](#channels)
26
- - [Tags](#tags)
3
+ [Documentation](https://activitysmith.com/docs/sdks/ruby)
27
4
 
28
5
  ## Installation
29
6
 
30
- ```sh
7
+ Install the ActivitySmith Ruby SDK with RubyGems:
8
+
9
+ ```bash
31
10
  gem install activitysmith
32
11
  ```
33
12
 
34
- ## Setup
13
+ ## Quickstart
14
+
15
+ 1. [Create an API key](https://activitysmith.com/app/keys)
16
+ 2. Set `ACTIVITYSMITH_API_KEY` or pass it directly to `ActivitySmith::Client`.
35
17
 
36
18
  ```ruby
37
19
  require "activitysmith"
38
20
 
39
- activitysmith = ActivitySmith::Client.new(api_key: ENV.fetch("ACTIVITYSMITH_API_KEY"))
21
+ activitysmith = ActivitySmith::Client.new(
22
+ api_key: ENV["ACTIVITYSMITH_API_KEY"]
23
+ )
40
24
  ```
41
25
 
42
26
  ## Push Notifications
43
27
 
44
28
  ### Send a Push Notification
45
29
 
46
- <p align="center">
47
- <img src="https://cdn.activitysmith.com/features/new-subscription-push-notification.png" alt="Push notification example" width="680" />
48
- </p>
30
+ Send an immediate notification for a completed task or event.
31
+
32
+ ![Push Notification example for a new subscription event](https://cdn.activitysmith.com/features/new-subscription-push-notification.png)
49
33
 
50
34
  ```ruby
51
35
  activitysmith.notifications.send(
@@ -58,26 +42,21 @@ activitysmith.notifications.send(
58
42
 
59
43
  ### Rich Push Notifications with Media
60
44
 
61
- <p align="center">
62
- <img src="https://cdn.activitysmith.com/features/rich-push-notification-with-image.png" alt="Rich push notification with image" width="680" />
63
- </p>
45
+ ![Rich Push Notification with image](https://cdn.activitysmith.com/features/rich-push-notification-with-image.png)
64
46
 
65
47
  ```ruby
66
48
  activitysmith.notifications.send(
67
49
  {
68
50
  title: "Homepage ready",
69
51
  message: "Your agent finished the redesign.",
70
- media: "https://cdn.example.com/output/homepage-v2.png",
71
- redirection: "https://github.com/acme/web/pull/482"
52
+ media: "https://cdn.example.com/output/homepage-v2.png"
72
53
  }
73
54
  )
74
55
  ```
75
56
 
76
- Send images, videos, or audio with your push notifications, press and hold to preview media directly from the notification, then tap through to open the linked content.
57
+ Attach images, videos, or audio to your Push Notifications. Press and hold the notification to preview the media.
77
58
 
78
- <p align="center">
79
- <img src="https://cdn.activitysmith.com/features/rich-push-notification-with-audio.png" alt="Rich push notification with audio" width="680" />
80
- </p>
59
+ ![Rich Push Notification with audio](https://cdn.activitysmith.com/features/rich-push-notification-with-audio.png)
81
60
 
82
61
  What will work:
83
62
 
@@ -86,24 +65,54 @@ What will work:
86
65
  - direct video file URL: `.mp4`, `.mov`, etc.
87
66
  - URL that responds with a proper media `Content-Type`, even if the path has no extension
88
67
 
68
+ `media` cannot be combined with `actions`.
69
+
70
+ ### Push Notifications with Redirection
71
+
72
+ Open a web page, run an iOS Shortcut, or open an app when someone taps the notification. `redirection` supports:
73
+
74
+ - **HTTP/HTTPS:** Web pages, e.g. `https://example.com`
75
+ - **Shortcuts:** Run Jarvis with `shortcuts://run-shortcut?name=Jarvis` <!-- full-width -->
76
+ - **App deep links:** Installed apps or specific content within them
77
+ - **Spotify:** A track, e.g. `spotify:track:6rqhFgbbKwnb9MLmUQDhG6`
78
+ - **Termius:** `termius://` to open the app
79
+ - **Claude:** `claude://code` to open the Code tab
80
+ - **ChatGPT:** `chatgpt://` to open the app <!-- Verify ChatGPT URL scheme on iOS before publishing -->
81
+
82
+ ```ruby
83
+ activitysmith.notifications.send(
84
+ {
85
+ title: "Homepage ready",
86
+ message: "Your agent finished the redesign.",
87
+ redirection: "https://github.com/acme/web/pull/482"
88
+ }
89
+ )
90
+ ```
91
+
89
92
  ### Actionable Push Notifications
90
93
 
91
- <p align="center">
92
- <img src="https://cdn.activitysmith.com/features/actionable-push-notifications-2.png" alt="Actionable push notification example" width="680" />
93
- </p>
94
+ ![Actionable Push Notification with redirection and actions](https://cdn.activitysmith.com/features/actionable-push-notifications-2.png)
95
+
96
+ `open_url` actions open a web page, run an iOS Shortcut, or open an app when someone taps the button. Supported links:
94
97
 
95
- Push notification `redirection` and `actions` are optional. Use them to open HTTPS URLs, run a specific iPhone Shortcut with `shortcuts://run-shortcut?name=...`, or trigger backend webhook workflows.
96
- Webhooks are executed by the ActivitySmith backend.
98
+ - **HTTP/HTTPS:** Web pages, e.g. `https://example.com`
99
+ - **Shortcuts:** Run Jarvis with `shortcuts://run-shortcut?name=Jarvis` <!-- full-width -->
100
+ - **App deep links:** Installed apps or specific content within them
101
+ - **Spotify:** A track, e.g. `spotify:track:6rqhFgbbKwnb9MLmUQDhG6`
102
+ - **Termius:** `termius://` to open the app
103
+ - **Claude:** `claude://code` to open the Code tab
104
+ - **ChatGPT:** `chatgpt://` to open the app <!-- Verify ChatGPT URL scheme on iOS before publishing -->
105
+
106
+ Webhooks are executed by the ActivitySmith backend and must use HTTPS.
97
107
 
98
108
  ```ruby
99
109
  activitysmith.notifications.send(
100
110
  {
101
111
  title: "New subscription 💸",
102
112
  message: "Customer upgraded to Pro plan",
103
- redirection: "https://crm.example.com/customers/cus_9f3a1d", # Optional
104
- actions: [ # Optional (max 4)
113
+ actions: [
105
114
  {
106
- title: "Open CRM Profile",
115
+ title: "Open CRM",
107
116
  type: "open_url",
108
117
  url: "https://crm.example.com/customers/cus_9f3a1d"
109
118
  },
@@ -129,28 +138,51 @@ activitysmith.notifications.send(
129
138
 
130
139
  ## Live Activities
131
140
 
132
- There are six types of Live Activities:
141
+ Choose the Live Activity type that matches what you want to show:
142
+
143
+ - ![Value Live Activity showing revenue with a growth badge](https://cdn.activitysmith.com/features/value-live-activity.png) **Value**: Show a single value on your Lock Screen, such as revenue, a queue count, or a temperature.
144
+
145
+ - ![Stats Live Activity with six labeled sales metrics](https://cdn.activitysmith.com/features/stats-live-activity.png) **Stats**: Show up to 8 labeled values on your Lock Screen, from revenue and orders to uptime and conversion.
146
+
147
+ - ![Alert Live Activity showing a customer reactivation update](https://cdn.activitysmith.com/features/alert-live-activity.png) **Alert**: Show status updates with a clear message, badge, and icon. When you add an action button, `color` controls the button tint.
133
148
 
134
- - `stats`: best for showing business numbers side by side, such as revenue, sales, new users, conversion, refunds, or any other value you want visible at a glance
135
- - `metrics`: best for live percentage values that change often, like server CPU, memory usage, disk usage, or error rate
136
- - `segmented_progress`: best for anything that moves through clear stages, like deployments, onboarding flows, backups, ETL pipelines, migrations, and AI agent runs
137
- - `progress`: best for tracking real-time progress with percentage, like tasks, backups, migrations, syncs, or uploads
138
- - `alert`: best for status updates, such as feature adoption, reactivation, onboarding blockers, incidents, escalations, and other operational states
139
- - `timer`: best for countdowns and elapsed runtime, like benchmark runs, uploads, backups, transcodes, and long-running jobs
149
+ - ![Metrics Live Activity with CPU and memory values](https://cdn.activitysmith.com/features/metrics-live-activity-start.png) **Metrics**: Track two related values with segmented bars, such as CPU and memory.
150
+
151
+ - ![Segmented Progress Live Activity showing a workflow step](https://cdn.activitysmith.com/features/update-live-activity.png) **Segmented Progress**: Show progress through a known set of steps, like build, test, deploy, and verify.
152
+
153
+ - ![Progress Live Activity showing percentage completion](https://cdn.activitysmith.com/features/progress-live-activity.png) **Progress**: Show percentage progress for jobs that move continuously toward completion.
154
+
155
+ - ![Timer Live Activity showing a benchmark run countdown](https://cdn.activitysmith.com/features/timer-live-activity.png) **Timer**: Count down from a duration, or count up from 00:00 while a job runs.
140
156
 
141
157
  ### Start & Update Live Activity
142
158
 
143
159
  Use a stable `stream_key` to identify the metric, job, deployment, or system you want to keep visible. The first `stream(...)` call starts the Live Activity. Later calls with the same `stream_key` update it.
144
160
 
161
+ #### Value
162
+
163
+ ![Value Live Activity stream example](https://cdn.activitysmith.com/features/value-live-activity.png)
164
+
165
+ ```ruby
166
+ activitysmith.live_activities.stream(
167
+ "revenue-today",
168
+ {
169
+ content_state: {
170
+ title: "Revenue",
171
+ type: "value",
172
+ value: "$1,240",
173
+ color: "green",
174
+ icon: { symbol: "dollarsign.circle", color: "green" },
175
+ badge: { title: "↑ 18%", color: "purple" }
176
+ }
177
+ }
178
+ )
179
+ ```
180
+
181
+ Send a string or number in `value`. Strings keep their formatting, including currency symbols, units, and decimal places.
182
+
145
183
  #### Stats
146
184
 
147
- <p align="center">
148
- <img
149
- src="https://cdn.activitysmith.com/features/stats-live-activity.png"
150
- alt="Stats Live Activity stream example"
151
- width="680"
152
- />
153
- </p>
185
+ ![Stats Live Activity stream example](https://cdn.activitysmith.com/features/stats-live-activity.png)
154
186
 
155
187
  ```ruby
156
188
  activitysmith.live_activities.stream(
@@ -173,15 +205,28 @@ activitysmith.live_activities.stream(
173
205
  )
174
206
  ```
175
207
 
208
+ #### Alert
209
+
210
+ ![Alert Live Activity stream example](https://cdn.activitysmith.com/features/alert-live-activity.png)
211
+
212
+ ```ruby
213
+ activitysmith.live_activities.stream(
214
+ "customer-ops",
215
+ {
216
+ content_state: ActivitySmith::LiveActivities.content_state(
217
+ title: "Reactivation",
218
+ message: "Lumen came back after 2 weeks",
219
+ type: ActivitySmith::LiveActivities::TYPE_ALERT,
220
+ icon: ActivitySmith::LiveActivities.alert_icon("cloud.sun", color: "yellow"),
221
+ badge: ActivitySmith::LiveActivities.alert_badge("Customer", color: "magenta")
222
+ )
223
+ }
224
+ )
225
+ ```
226
+
176
227
  #### Metrics
177
228
 
178
- <p align="center">
179
- <img
180
- src="https://cdn.activitysmith.com/features/metrics-live-activity-start.png"
181
- alt="Metrics Live Activity stream example"
182
- width="680"
183
- />
184
- </p>
229
+ ![Metrics Live Activity stream example](https://cdn.activitysmith.com/features/metrics-live-activity-start.png)
185
230
 
186
231
  ```ruby
187
232
  activitysmith.live_activities.stream(
@@ -202,13 +247,7 @@ activitysmith.live_activities.stream(
202
247
 
203
248
  #### Segmented Progress
204
249
 
205
- <p align="center">
206
- <img
207
- src="https://cdn.activitysmith.com/features/update-live-activity.png"
208
- alt="Segmented Progress Live Activity stream example"
209
- width="680"
210
- />
211
- </p>
250
+ ![Segmented Progress Live Activity stream example](https://cdn.activitysmith.com/features/update-live-activity.png)
212
251
 
213
252
  ```ruby
214
253
  activitysmith.live_activities.stream(
@@ -227,13 +266,7 @@ activitysmith.live_activities.stream(
227
266
 
228
267
  #### Progress
229
268
 
230
- <p align="center">
231
- <img
232
- src="https://cdn.activitysmith.com/features/progress-live-activity.png"
233
- alt="Progress Live Activity stream example"
234
- width="680"
235
- />
236
- </p>
269
+ ![Progress Live Activity stream example](https://cdn.activitysmith.com/features/progress-live-activity.png)
237
270
 
238
271
  ```ruby
239
272
  activitysmith.live_activities.stream(
@@ -249,40 +282,9 @@ activitysmith.live_activities.stream(
249
282
  )
250
283
  ```
251
284
 
252
- #### Alert
253
-
254
- <p align="center">
255
- <img
256
- src="https://cdn.activitysmith.com/features/alert-live-activity.png"
257
- alt="Alert Live Activity stream example"
258
- width="680"
259
- />
260
- </p>
261
-
262
- ```ruby
263
- activitysmith.live_activities.stream(
264
- "customer-ops",
265
- {
266
- content_state: ActivitySmith::LiveActivities.content_state(
267
- title: "Reactivation",
268
- message: "Lumen came back after 2 weeks",
269
- type: ActivitySmith::LiveActivities::TYPE_ALERT,
270
- icon: ActivitySmith::LiveActivities.alert_icon("cloud.sun", color: "yellow"),
271
- badge: ActivitySmith::LiveActivities.alert_badge("Customer", color: "magenta")
272
- )
273
- }
274
- )
275
- ```
276
-
277
285
  #### Timer
278
286
 
279
- <p align="center">
280
- <img
281
- src="https://cdn.activitysmith.com/features/timer-live-activity.png"
282
- alt="Timer Live Activity showing a benchmark run countdown"
283
- width="680"
284
- />
285
- </p>
287
+ ![Timer Live Activity stream example](https://cdn.activitysmith.com/features/timer-live-activity.png)
286
288
 
287
289
  ```ruby
288
290
  activitysmith.live_activities.stream(
@@ -305,7 +307,7 @@ To start at 00:00 and count up, set `counts_down: false` and leave out `duration
305
307
 
306
308
  ### End Live Activity
307
309
 
308
- Call `end_stream(...)` with the same `stream_key` to dismiss the Live Activity. You can include final values before it is removed. By default, iOS removes the Live Activity after two minutes. Set `auto_dismiss_minutes` to choose a different dismissal time, including `0` for immediate dismissal.
310
+ Call `end_stream(...)` with the same `stream_key` to dismiss the Live Activity. You can include final values before it is removed. Set `auto_dismiss_seconds` to dismiss it after a delay in seconds, or `auto_dismiss_minutes` for minutes. Use `0` for immediate dismissal. Seconds take precedence if both are set.
309
311
 
310
312
  ```ruby
311
313
  activitysmith.live_activities.end_stream(
@@ -319,30 +321,89 @@ activitysmith.live_activities.end_stream(
319
321
  { label: "CPU", value: 7, unit: "%" },
320
322
  { label: "MEM", value: 38, unit: "%" }
321
323
  ],
322
- auto_dismiss_minutes: 2
324
+ auto_dismiss_seconds: 30
323
325
  }
324
326
  }
325
327
  )
326
328
  ```
327
329
 
330
+ ### Icons and Badges
331
+
332
+ Add more context to Live Activities with icons and badges.
333
+
334
+ #### Icon
335
+
336
+ Supported Live Activity types: `value`, `stats`, `alert`, `metrics`, `segmented_progress`, `progress`, and `timer`.
337
+
338
+ ![Metrics Live Activity with an SF Symbol icon on the iPhone Lock Screen](https://cdn.activitysmith.com/features/metrics-live-activity-with-icon.png)
339
+
340
+ ```ruby
341
+ activitysmith.live_activities.stream(
342
+ "prod-web-1",
343
+ {
344
+ content_state: ActivitySmith::LiveActivities.content_state(
345
+ title: "Server Health",
346
+ subtitle: "prod-web-1",
347
+ type: "metrics",
348
+ icon: ActivitySmith::LiveActivities.alert_icon("server.rack", color: "blue"),
349
+ metrics: [
350
+ { label: "CPU", value: 18, unit: "%" },
351
+ { label: "MEM", value: 42, unit: "%" }
352
+ ]
353
+ )
354
+ }
355
+ )
356
+ ```
357
+
358
+ The `icon` symbol value is an Apple SF Symbol name. Browse the catalog with one of these tools:
359
+
360
+ - [ActivitySmith app](https://apps.apple.com/us/app/activitysmith/id6752254835) - Open Settings -> SF Symbols to browse 45 hand-picked icons ready to use
361
+ - [SF Symbols](https://developer.apple.com/sf-symbols/) - Apple's official macOS app
362
+ - [Interactful](https://apps.apple.com/app/interactful/id1528095640) - free third-party iOS app listing all SF Symbols under Foundations -> Iconography
363
+
364
+ #### Badge
365
+
366
+ Badges are supported by `value`, `alert`, `segmented_progress`, and `progress` Live Activities.
367
+
368
+ ![Progress Live Activity with a badge on the iPhone Lock Screen](https://cdn.activitysmith.com/features/progress-live-activity-with-badge.png)
369
+
370
+ ```ruby
371
+ activitysmith.live_activities.stream(
372
+ "nightly-database-backup",
373
+ {
374
+ content_state: ActivitySmith::LiveActivities.content_state(
375
+ title: "Nightly Database Backup",
376
+ subtitle: "verify restore",
377
+ type: "progress",
378
+ badge: ActivitySmith::LiveActivities.alert_badge("S3", color: "cyan"),
379
+ percentage: 62
380
+ )
381
+ }
382
+ )
383
+ ```
384
+
385
+ ### Live Activity Colors
386
+
387
+ Choose from these colors for the Live Activity accent, including progress bars and action buttons, or apply them to an individual icon or badge:
388
+
389
+ `lime`, `green`, `cyan`, `blue`, `purple`, `magenta`, `red`, `orange`, `yellow`, `gray`
390
+
328
391
  ### Live Activity Action
329
392
 
330
- Live Activities can include an action button.
393
+ ![Metrics Live Activity with action](https://cdn.activitysmith.com/features/metrics-live-activity-action.png)
331
394
 
332
- - `open_url`: open an HTTPS URL.
333
- - `open_url` with a `shortcuts://` URL: run an Apple Shortcut, for example to open an app.
334
- - `webhook`: trigger a backend GET/POST workflow.
395
+ Live Activities can include an action button.
335
396
 
336
- <p align="center">
337
- <img
338
- src="https://cdn.activitysmith.com/features/metrics-live-activity-action.png"
339
- alt="Live Activity with action button"
340
- width="680"
341
- />
342
- </p>
397
+ - `open_url`: Open a web page or run an iOS Shortcut
398
+ - `webhook`: Trigger a backend GET/POST workflow
343
399
 
344
400
  #### Open URL action
345
401
 
402
+ Open a web page or run an iOS Shortcut when someone taps the button. Supported links:
403
+
404
+ - **HTTP/HTTPS:** Web pages, e.g. `https://example.com`
405
+ - **Shortcuts:** Run Jarvis with `shortcuts://run-shortcut?name=Jarvis` <!-- full-width -->
406
+
346
407
  ```ruby
347
408
  activitysmith.live_activities.stream(
348
409
  "prod-web-1",
@@ -359,7 +420,7 @@ activitysmith.live_activities.stream(
359
420
  action: {
360
421
  title: "Dashboard",
361
422
  type: "open_url",
362
- url: "https://ops.example.com/servers/prod-web-1"
423
+ url: "https://status.example.com/servers/prod-web-1"
363
424
  }
364
425
  }
365
426
  )
@@ -369,14 +430,16 @@ activitysmith.live_activities.stream(
369
430
 
370
431
  ```ruby
371
432
  activitysmith.live_activities.stream(
372
- "deploy-payments-api",
433
+ "prod-web-1",
373
434
  {
374
435
  content_state: {
375
- title: "Deploying payments-api",
376
- subtitle: "Running database migrations",
377
- type: "segmented_progress",
378
- number_of_steps: 5,
379
- current_step: 3
436
+ title: "Server Health",
437
+ subtitle: "prod-web-1",
438
+ type: "metrics",
439
+ metrics: [
440
+ { label: "CPU", value: 76, unit: "%" },
441
+ { label: "MEM", value: 52, unit: "%" }
442
+ ]
380
443
  },
381
444
  action: {
382
445
  title: "Chat with Jarvis",
@@ -416,17 +479,11 @@ activitysmith.live_activities.stream(
416
479
 
417
480
  #### Secondary action
418
481
 
419
- <p align="center">
420
- <img
421
- src="https://cdn.activitysmith.com/features/live-activity-secondary-action.png"
422
- alt="Alert Live Activity with primary and secondary action buttons"
423
- width="680"
424
- />
425
- </p>
482
+ ![Alert Live Activity with primary and secondary action buttons](https://cdn.activitysmith.com/features/live-activity-secondary-action.png)
426
483
 
427
484
  Use `secondary_action` when you want a second button beside the primary `action`.
428
485
 
429
- The secondary action button is supported for `alert`, `progress`, and `segmented_progress` Live Activities. Both buttons use the same `open_url`, `webhook`, and Apple Shortcut payload shapes.
486
+ The secondary action button is supported for `value`, `alert`, `segmented_progress`, and `progress` Live Activities. Both buttons use the same `open_url`, `webhook`, and Apple Shortcut payload shapes.
430
487
 
431
488
  ```ruby
432
489
  activitysmith.live_activities.stream(
@@ -464,90 +521,15 @@ activitysmith.live_activities.stream(
464
521
  )
465
522
  ```
466
523
 
467
- ### Icons and Badges
468
-
469
- Add more context to Live Activities with icons and badges.
470
-
471
- #### Icon
472
-
473
- Supported Live Activity types: `stats`, `metrics`, `progress`, `segmented_progress`, `alert`, and `timer`.
474
-
475
- <p align="center">
476
- <img
477
- src="https://cdn.activitysmith.com/features/metrics-live-activity-with-icon.png"
478
- alt="Metrics Live Activity with an SF Symbol icon on the iPhone Lock Screen"
479
- width="680"
480
- />
481
- </p>
482
-
483
- ```ruby
484
- activitysmith.live_activities.stream(
485
- "prod-web-1",
486
- {
487
- content_state: ActivitySmith::LiveActivities.content_state(
488
- title: "Server Health",
489
- subtitle: "prod-web-1",
490
- type: "metrics",
491
- icon: ActivitySmith::LiveActivities.alert_icon("server.rack", color: "blue"),
492
- metrics: [
493
- { label: "CPU", value: 18, unit: "%" },
494
- { label: "MEM", value: 42, unit: "%" }
495
- ]
496
- )
497
- }
498
- )
499
- ```
500
-
501
- The `icon` symbol value is an Apple SF Symbol name. Browse the catalog with one of these tools:
502
-
503
- - [ActivitySmith app](https://apps.apple.com/us/app/activitysmith/id6752254835) - Open Settings -> SF Symbols to browse 45 hand-picked icons ready to use
504
- - [SF Symbols](https://developer.apple.com/sf-symbols/) - Apple's official macOS app
505
- - [Interactful](https://apps.apple.com/app/interactful/id1528095640) - free third-party iOS app listing all SF Symbols under Foundations -> Iconography
506
-
507
- #### Badge
508
-
509
- Badges are supported by `alert`, `progress`, and `segmented_progress` Live Activities.
510
-
511
- <p align="center">
512
- <img
513
- src="https://cdn.activitysmith.com/features/progress-live-activity-with-badge.png"
514
- alt="Progress Live Activity with a badge on the iPhone Lock Screen"
515
- width="680"
516
- />
517
- </p>
518
-
519
- ```ruby
520
- activitysmith.live_activities.stream(
521
- "nightly-database-backup",
522
- {
523
- content_state: ActivitySmith::LiveActivities.content_state(
524
- title: "Nightly Database Backup",
525
- subtitle: "verify restore",
526
- type: "progress",
527
- badge: ActivitySmith::LiveActivities.alert_badge("S3", color: "cyan"),
528
- percentage: 62
529
- )
530
- }
531
- )
532
- ```
533
-
534
- ### Live Activity Colors
535
-
536
- Choose from these colors for the Live Activity accent, including progress bars and action buttons, or apply them to an individual icon or badge:
537
-
538
- `lime`, `green`, `cyan`, `blue`, `purple`, `magenta`, `red`, `orange`, `yellow`, `gray`
524
+ ## Lock Screen Widgets
539
525
 
540
- ## Widgets
526
+ ![Lock screen widgets](https://cdn.activitysmith.com/features/lock-screen-widgets.png)
541
527
 
542
- <p align="center">
543
- <img src="https://cdn.activitysmith.com/features/lock-screen-widgets.png" alt="Lock screen widgets" width="680" />
544
- </p>
528
+ ActivitySmith lets you display any value on your Lock Screen with widgets - SaaS metrics, revenue, signups, uptime, habits, or anything else you want to track. Create a metric in the [web app](https://activitysmith.com/app/widgets), then update the metric value using our API, add a widget to your lock screen and it will fetch the latest update automatically.
545
529
 
546
- ActivitySmith lets you display any value on your Lock Screen with widgets - SaaS metrics, revenue, signups, uptime, habits, or anything else you want to track. Create a metric in the <a href="https://activitysmith.com/app/widgets" target="_blank" rel="noopener noreferrer">web app</a>, then update the metric value using our API, add a widget to your lock screen and it will fetch the latest update automatically.
530
+ ![Create widget metric](https://cdn.activitysmith.com/features/create-widget-metric.png)
547
531
 
548
- <p align="center">
549
- <img src="https://cdn.activitysmith.com/features/create-widget-metric.png" alt="Create widget metric" width="680" />
550
- </p>
532
+ Use the metric key to update its value.
551
533
 
552
534
  ```ruby
553
535
  activitysmith.metrics.update("deploy.success_rate", 99.9)
@@ -561,92 +543,129 @@ activitysmith.metrics.update("prod.status", "healthy")
561
543
 
562
544
  ## App Icon Badge Count
563
545
 
564
- <p align="center">
565
- <img src="https://cdn.activitysmith.com/features/badge-count.png" alt="ActivitySmith app icon with an App Icon Badge Count" width="680" />
566
- </p>
546
+ ![ActivitySmith app icon with an App Icon Badge Count](https://cdn.activitysmith.com/features/badge-count.png)
567
547
 
568
548
  Show the number you care about on your ActivitySmith app icon. Track MRR, a customer count, a stock price, or any other value you want to keep in view.
569
549
 
570
- Set or update the badge value.
550
+ ### Set or update the badge value
571
551
 
572
552
  ```ruby
573
553
  activitysmith.badge_count(8333)
574
554
  ```
575
555
 
576
- To clear the badge, set its value to 0.
556
+ ### Clear the badge
557
+
558
+ Pass `0` to clear the badge.
577
559
 
578
560
  ```ruby
579
561
  activitysmith.badge_count(0)
580
562
  ```
581
563
 
582
- ## Channels
583
-
584
- Use `channels` to target specific team members or devices
564
+ ## Metadata
585
565
 
586
- ### Push Notifications
566
+ Metadata adds extra information to Push Notification and Live Activity details in ActivitySmith. It does not appear in the notification or Live Activity on your device.
587
567
 
588
568
  ```ruby
589
569
  activitysmith.notifications.send(
590
- {
591
- title: "New subscription 💸",
592
- message: "Customer upgraded to Pro plan",
593
- channels: ["sales", "customer-success"]
570
+ title: "New subscription 💸",
571
+ message: "Customer upgraded to Pro plan",
572
+ metadata: {
573
+ customer_id: "382",
574
+ plan: "Pro",
575
+ amount: 29,
576
+ trial: false,
577
+ }
578
+ )
579
+
580
+ activitysmith.live_activities.stream(
581
+ "customer-import",
582
+ content_state: {
583
+ title: "Customer Import",
584
+ type: "progress",
585
+ percentage: 60,
586
+ },
587
+ metadata: {
588
+ job_id: "import-382",
589
+ records: 1200,
594
590
  }
595
591
  )
596
592
  ```
597
593
 
598
- ### Live Activities
594
+ Values can be strings, numbers, or booleans. Metadata supports up to 50 entries and 16 KB of JSON, with keys up to 100 characters and strings up to 4,000 characters. Nested objects, arrays, and null values are not supported.
595
+
596
+ ## Tags
597
+
598
+ Use `tags` to organize and filter your Push Notification and Live Activity history. Tags are created automatically when you first use them.
599
599
 
600
600
  ```ruby
601
- activitysmith.live_activities.start(
601
+ activitysmith.notifications.send(
602
602
  {
603
- content_state: {
604
- title: "Nightly Database Backup",
605
- subtitle: "verify restore",
606
- type: "progress",
607
- percentage: 62
608
- },
609
- channels: ["sales", "customer-success"]
603
+ title: "New subscription 💸",
604
+ message: "Customer upgraded to Pro plan",
605
+ tags: ["user:382", "billing"]
610
606
  }
611
607
  )
612
608
  ```
613
609
 
614
- ### App Icon Badge Count
610
+ On Live Activity stream updates and legacy `update` or `end` calls, omit `tags` to keep existing Tags, supply a list to replace them, or pass `tags: []` to clear them.
615
611
 
616
612
  ```ruby
617
- activitysmith.badge_count(3, channels: ["sales", "customer-success"])
613
+ activitysmith.live_activities.update(
614
+ activity_id: "YOUR_ACTIVITY_ID",
615
+ content_state: { title: "Customer Import", percentage: 60 },
616
+ tags: []
617
+ )
618
618
  ```
619
619
 
620
- ## Tags
620
+ ## Channels
621
621
 
622
- Use `tags` to organize and filter your Push Notification and Live Activity history. Tags are created automatically when you first use them.
622
+ Use `channels` to target specific team members or devices when sending Push Notifications, Live Activities, or App Icon Badge Count updates. Omit it for account-wide delivery.
623
623
 
624
624
  ```ruby
625
625
  activitysmith.notifications.send(
626
626
  {
627
627
  title: "New subscription 💸",
628
628
  message: "Customer upgraded to Pro plan",
629
- tags: ["user:382", "billing"]
629
+ channels: ["sales", "customer-success"]
630
630
  }
631
631
  )
632
+
633
+ activitysmith.live_activities.stream(
634
+ "nightly-backup",
635
+ {
636
+ channels: ["ios-builds"],
637
+ content_state: {
638
+ title: "Nightly database backup",
639
+ number_of_steps: 3,
640
+ current_step: 1,
641
+ type: "segmented_progress"
642
+ }
643
+ }
644
+ )
645
+
646
+ activitysmith.badge_count(3, channels: ["sales", "customer-success"])
632
647
  ```
633
648
 
634
649
  ## Error Handling
635
650
 
651
+ Handle API errors with `begin/rescue` around SDK calls:
652
+
636
653
  ```ruby
637
654
  begin
638
655
  activitysmith.notifications.send(
639
- { title: "New subscription 💸" }
656
+ { title: "Hello" }
640
657
  )
641
658
  rescue OpenapiClient::ApiError => err
642
659
  puts "Request failed: #{err.code} #{err.message}"
643
660
  end
644
661
  ```
645
662
 
646
- ## Requirements
663
+ ## Additional Resources
664
+
665
+ ### [RubyGems Package](https://rubygems.org/gems/activitysmith)
647
666
 
648
- - Ruby 3.0+
667
+ Install the ActivitySmith Ruby SDK from RubyGems
649
668
 
650
- ## License
669
+ ### [Source Code](https://github.com/ActivitySmithHQ/activitysmith-ruby)
651
670
 
652
- MIT
671
+ View the Ruby SDK source on GitHub