Targeting

Control which subscribers receive each notification using a discriminated targeting object. The "type" field selects one of the five shapes below, and the API validates the whole object when the notification is created: an unknown type, a missing field (ids, tags, platforms), an empty list, or an unknown platform is a 422 with the reason in errors.targeting. Nothing is sent.

Validated on write

Earlier versions accepted any shape and fell through to "all subscribers", so a typo in "type" was a broadcast. That is no longer possible: a notification either has one of the shapes below or it is not created.

Supported targeting shapes

Shape	Audience	Notes
{"type": "all"}	every active subscriber for the app	also the default when targeting is omitted entirely
{"type": "user_ids", "ids": ["user-1"]}	subscribers whose user_id matches any in the list	targets every device registered to those users
{"type": "tags", "tags": ["beta"], "match": "any"}	subscribers tagged with at least one of the listed tags	OR semantics
{"type": "tags", "tags": ["beta", "ios"], "match": "all"}	subscribers tagged with all of the listed tags	AND semantics
{"type": "platform", "platforms": ["web", "ios"]}	subscribers whose registered platform is in the list	values: web, ios, android

You can pick exactly one shape per notification — there is no combiner today. To send to "premium tagged users plus specific user IDs", send two notifications.

Tag-Based Targeting

Tags are string labels assigned to subscribers at registration time. Use them to group subscribers by interest, feature access, or any other dimension.

Assigning Tags

Include tags when registering a subscriber:

curl -X POST https://app.krafter.dev/api/v1/push/apps/:app_id/subscribers \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "web",
    "token": "{\"endpoint\":\"https://fcm.googleapis.com/fcm/send/eKqL...\",\"keys\":{\"p256dh\":\"BNcRd...\",\"auth\":\"tBHI...\"}}",
    "user_id": "user_456",
    "tags": ["beta", "newsletter", "premium"]
  }'

Targeting by Tags (any-match)

Send to subscribers tagged with any of the listed tags:

curl -X POST https://app.krafter.dev/api/v1/push/apps/:app_id/notifications \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Beta Feature Available",
    "body": "Try out the new dashboard redesign",
    "url": "https://example.com/beta",
    "targeting": {
      "type": "tags",
      "tags": ["beta", "early-access"],
      "match": "any"
    },
    "send": true
  }'

Targeting by Tags (all-match)

Send only to subscribers tagged with every listed tag:

{
  "targeting": {
    "type": "tags",
    "tags": ["premium", "ios"],
    "match": "all"
  }
}

This sends only to subscribers tagged with both premium andios. match defaults to "any" when omitted, and the stored notification carries the resolved value.

User ID Targeting

Assign a user_id when registering subscribers to target specific users by your application's identifier. This is useful for transactional notifications like order updates or account alerts.

Assigning User IDs

curl -X POST https://app.krafter.dev/api/v1/push/apps/:app_id/subscribers \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "web",
    "token": "{\"endpoint\":\"https://fcm.googleapis.com/fcm/send/eKqL...\",\"keys\":{\"p256dh\":\"BNcRd...\",\"auth\":\"tBHI...\"}}",
    "user_id": "user_789"
  }'

A single user can have multiple subscribers (one per device or browser). Targeting by user_id delivers to every device registered under that ID.

Targeting by User IDs

Send a notification to specific users:

curl -X POST https://app.krafter.dev/api/v1/push/apps/:app_id/notifications \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Your order shipped!",
    "body": "Order #1234 is on its way",
    "url": "https://example.com/orders/1234",
    "targeting": {
      "type": "user_ids",
      "ids": ["user_789"]
    },
    "send": true
  }'

The field is ids (not user_ids). Multiple user IDs can be specified to target a group:

{
  "targeting": {
    "type": "user_ids",
    "ids": ["user_789", "user_456", "user_321"]
  }
}

Platform Targeting

Send only to subscribers whose registered platform matches one of the listed values. Supported values: web, ios, android.

curl -X POST https://app.krafter.dev/api/v1/push/apps/:app_id/notifications \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "iOS app update",
    "body": "Tap to update to v2.4",
    "url": "https://example.com/app",
    "targeting": {
      "type": "platform",
      "platforms": ["ios"]
    },
    "send": true
  }'

Broadcast (all subscribers)

Either send {"type": "all"} or omit targeting entirely:

curl -X POST https://app.krafter.dev/api/v1/push/apps/:app_id/notifications \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Maintenance Notice",
    "body": "Scheduled downtime tonight at 11 PM UTC",
    "url": "https://example.com/status",
    "send": true
  }'

TIP

Use broadcast sparingly. Targeted notifications have higher click rates and lower unsubscribe rates than bulk messages.

Segments are not supported

Earlier versions of these docs referenced a segments targeting shape ({"segments": ["uuid"]}). No segment system exists in the codebase today — such a payload is rejected with a 422. If you need saved-audience semantics, build them on top of tag combinations or file a feature request.

Targeting Summary

Strategy	Shape	Matches
All / broadcast	{"type": "all"} or omit targeting	every active subscriber
User IDs	{"type": "user_ids", "ids": [...]}	all devices for the listed users
Tags (any)	{"type": "tags", "tags": [...], "match": "any"}	subscribers with at least one matching tag
Tags (all)	{"type": "tags", "tags": [...], "match": "all"}	subscribers with every listed tag
Platform	{"type": "platform", "platforms": [...]}	subscribers whose registered platform matches

Next Steps

• Web Push Setup -- Browser subscription and service worker setup
• Quickstart -- End-to-end push notification walkthrough
• API Reference -- Full endpoint documentation for apps, subscribers, and notifications