ActivitySmith Ruby SDK
The ActivitySmith Ruby SDK provides convenient access to the ActivitySmith API from Ruby applications.
Documentation
See API reference.
Table of Contents
Installation
gem install activitysmith
Setup
require "activitysmith"
activitysmith = ActivitySmith::Client.new(api_key: ENV.fetch("ACTIVITYSMITH_API_KEY"))
Push Notifications
Send a Push Notification
activitysmith.notifications.send(
{
title: "New subscription 💸",
message: "Customer upgraded to Pro plan"
}
)
Rich Push Notifications with Media
activitysmith.notifications.send(
{
title: "Homepage ready",
message: "Your agent finished the redesign.",
media: "https://cdn.example.com/output/homepage-v2.png",
redirection: "https://github.com/acme/web/pull/482"
}
)
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.
What will work:
- direct image URL:
.jpg,.png,.gif, etc. - direct audio file URL:
.mp3,.m4a, etc. - direct video file URL:
.mp4,.mov, etc. - URL that responds with a proper media
Content-Type, even if the path has no extension
Actionable Push Notifications
Actionable push notifications can open a URL on tap or trigger actions when someone long-presses the notification. Webhooks are executed by the ActivitySmith backend.
activitysmith.notifications.send(
{
title: "New subscription 💸",
message: "Customer upgraded to Pro plan",
redirection: "https://crm.example.com/customers/cus_9f3a1d", # Optional
actions: [ # Optional (max 4)
{
title: "Open CRM Profile",
type: "open_url",
url: "https://crm.example.com/customers/cus_9f3a1d"
},
{
title: "Start Onboarding Workflow",
type: "webhook",
url: "https://hooks.example.com/activitysmith/onboarding/start",
method: "POST",
body: {
customer_id: "cus_9f3a1d",
plan: "pro"
}
}
]
}
)
Live Activities
There are five types of Live Activities:
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 glancemetrics: best for live percentage values that change often, like server CPU, memory usage, disk usage, or error ratesegmented_progress: best for anything that moves through clear stages, like deployments, onboarding flows, backups, ETL pipelines, migrations, and AI agent runsprogress: best for tracking real-time progress with percentage, like tasks, backups, migrations, syncs, or uploadsalert: best for status updates, such as feature adoption, reactivation, onboarding blockers, incidents, escalations, and other operational states
Start & Update Live Activity
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.
Stats
activitysmith.live_activities.stream(
"sales-hourly",
{
content_state: {
title: "Sales",
subtitle: "last hour",
type: "stats",
metrics: [
{ label: "Revenue", value: "$2430", color: "blue" },
{ label: "Orders", value: "37", color: "green" },
{ label: "Conversion", value: "4.8%", color: "magenta" },
{ label: "Avg Order", value: "$65.68", color: "yellow" },
{ label: "Refunds", value: "$84", color: "red" },
{ label: "New Buyers", value: "18", color: "cyan" }
]
}
}
)
Metrics
activitysmith.live_activities.stream(
"prod-web-1",
{
content_state: {
title: "Server Health",
subtitle: "prod-web-1",
type: "metrics",
metrics: [
{ label: "CPU", value: 9, unit: "%" },
{ label: "MEM", value: 45, unit: "%" }
]
}
}
)
Segmented Progress
activitysmith.live_activities.stream(
"nightly-backup",
{
content_state: {
title: "Nightly Backup",
subtitle: "upload archive",
type: "segmented_progress",
number_of_steps: 3,
current_step: 2
}
}
)
Progress
activitysmith.live_activities.stream(
"search-reindex",
{
content_state: {
title: "Search Reindex",
subtitle: "catalog-v2",
type: "progress",
percentage: 42
}
}
)
Alert
activitysmith.live_activities.stream(
"customer-ops",
{
content_state: ActivitySmith::LiveActivities.content_state(
title: "Reactivation",
message: "Lumen came back after 2 weeks",
type: ActivitySmith::LiveActivities::TYPE_ALERT,
icon: ActivitySmith::LiveActivities.alert_icon("cloud.sun", color: "yellow"),
badge: ActivitySmith::LiveActivities.alert_badge("Customer", color: "magenta")
)
}
)
The icon symbol value is an Apple SF Symbol name. Browse the catalog with one of these tools:
- ActivitySmith app - Open Settings -> SF Symbols to browse 45 hand-picked icons ready to use
- SF Symbols - Apple's official macOS app
- Interactful - free third-party iOS app listing all SF Symbols under Foundations -> Iconography
icon and badge are optional. If you omit either one, that element is not shown in the Live Activity.
End Live Activity
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.
activitysmith.live_activities.end_stream(
"prod-web-1",
{
content_state: {
title: "Server Health",
subtitle: "prod-web-1",
type: "metrics",
metrics: [
{ label: "CPU", value: 7, unit: "%" },
{ label: "MEM", value: 38, unit: "%" }
],
auto_dismiss_minutes: 2
}
}
)
Live Activity Action
Live Activities can include one optional action button. Use it to open a URL from the Live Activity or trigger a backend webhook.
For Alert Live Activities, set color in content_state to tint the action button. Icon and badge colors only affect the icon and badge.
Open URL action
activitysmith.live_activities.stream(
"prod-web-1",
{
content_state: {
title: "Server Health",
subtitle: "prod-web-1",
type: "metrics",
metrics: [
{ label: "CPU", value: 76, unit: "%" },
{ label: "MEM", value: 52, unit: "%" }
]
},
action: {
title: "Open Dashboard",
type: "open_url",
url: "https://ops.example.com/servers/prod-web-1"
}
}
)
Webhook action
activitysmith.live_activities.stream(
"search-reindex",
{
content_state: {
title: "Reindexing product search",
subtitle: "Shard 7 of 12",
type: "segmented_progress",
number_of_steps: 12,
current_step: 7
},
action: {
title: "Pause Reindex",
type: "webhook",
url: "https://ops.example.com/hooks/search/reindex/pause",
method: "POST",
body: {
job_id: "reindex-2026-03-19",
requested_by: "activitysmith-ruby"
}
}
}
)
Channels
Channels are used to target specific team members or devices. Can be used for both push notifications and live activities.
activitysmith.notifications.send(
{
title: "New subscription 💸",
message: "Customer upgraded to Pro plan",
channels: ["sales", "customer-success"] # Optional
}
)
Widgets
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, then update the metric value using our API, add a widget to your lock screen and it will fetch the latest update automatically.
activitysmith.metrics.update("deploy.success_rate", 99.9)
String metric values work too.
activitysmith.metrics.update("prod.status", "healthy")
Error Handling
begin
activitysmith.notifications.send(
{ title: "New subscription 💸" }
)
rescue OpenapiClient::ApiError => err
puts "Request failed: #{err.code} #{err.}"
end
Requirements
- Ruby 3.0+
License
MIT