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
• Setup
• Push Notifications
  • Send a Push Notification
  • Rich Push Notifications with Media
  • Actionable Push Notifications
• Live Activities
  • Start & Update Live Activity
  • End Live Activity
  • Live Activity Action
  • Icons and Badges
  • Live Activity Colors
• Channels
• Widgets

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

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. 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: "Chat with Jarvis",
        type: "open_url",
        url: "shortcuts://run-shortcut?name=Jarvis"
      },
      {
        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 six 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 glance
• metrics: best for live percentage values that change often, like server CPU, memory usage, disk usage, or error rate
• segmented_progress: best for anything that moves through clear stages, like deployments, onboarding flows, backups, ETL pipelines, migrations, and AI agent runs
• progress: best for tracking real-time progress with percentage, like tasks, backups, migrations, syncs, or uploads
• alert: best for status updates, such as feature adoption, reactivation, onboarding blockers, incidents, escalations, and other operational states
• timer: best for countdowns and elapsed runtime, like benchmark runs, uploads, backups, transcodes, and long-running jobs

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")
    )
  }
)

Timer

activitysmith.live_activities.stream(
  "benchmark-run",
  {
    content_state: {
      title: "Benchmark Run",
      subtitle: "sampling",
      type: "timer",
      duration_seconds: 300,
      color: "cyan"
    }
  }
)

For a countdown, send duration_seconds. You can update title, subtitle, color, or any other visible field as the work changes. Leave duration_seconds out unless you want to change the timer.

To start at 00:00 and count up, set counts_down: false and leave out duration_seconds.

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.

• open_url: open an HTTPS URL.
• open_url with a shortcuts://run-shortcut?name=... URL: run a specific iPhone Shortcut, for example to open an app.
• webhook: trigger a backend GET/POST workflow.

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: "Dashboard",
      type: "open_url",
      url: "https://ops.example.com/servers/prod-web-1"
    }
  }
)

Apple Shortcut action

activitysmith.live_activities.stream(
  "deploy-payments-api",
  {
    content_state: {
      title: "Deploying payments-api",
      subtitle: "Running database migrations",
      type: "segmented_progress",
      number_of_steps: 5,
      current_step: 3
    },
    action: {
      title: "Chat with Jarvis",
      type: "open_url",
      url: "shortcuts://run-shortcut?name=Jarvis"
    }
  }
)

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"
      }
    }
  }
)

Icons and Badges

Add more context to Live Activities with icons and badges.

Icon

Supported Live Activity types: stats, metrics, progress, segmented_progress, alert, and timer.

activitysmith.live_activities.stream(
  "prod-web-1",
  {
    content_state: ActivitySmith::LiveActivities.content_state(
      title: "Server Health",
      subtitle: "prod-web-1",
      type: "metrics",
      icon: ActivitySmith::LiveActivities.alert_icon("server.rack", color: "blue"),
      metrics: [
        { label: "CPU", value: 18, unit: "%" },
        { label: "MEM", value: 42, unit: "%" }
      ]
    )
  }
)

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

Badge

Badges are supported by alert, progress, and segmented_progress Live Activities.

activitysmith.live_activities.stream(
  "nightly-database-backup",
  {
    content_state: ActivitySmith::LiveActivities.content_state(
      title: "Nightly Database Backup",
      subtitle: "verify restore",
      type: "progress",
      badge: ActivitySmith::LiveActivities.alert_badge("S3", color: "cyan"),
      percentage: 62
    )
  }
)

Live Activity Colors

Choose from these colors for the Live Activity accent, including progress bars and action buttons, or apply them to an individual icon or badge:

lime, green, cyan, blue, purple, magenta, red, orange, yellow, gray

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.message}"
end

Requirements

• Ruby 3.0+

License

MIT