Push Notifications

Send targeted push notifications to your users across iOS (APNS), Android (FCM), and Web Push (browsers).

Overview

Push notifications allow you to:

• Re-engage users who haven't opened your app recently
• Drive conversions with time-sensitive offers
• Deliver updates about orders, messages, or app events
• Personalize messaging based on user behavior and attributes

Prerequisites

Before creating push campaigns, ensure you have:

1. Integrated an SDK:

   • iOS SDK for iPhone/iPad users
   • Android SDK for Android users
   • Web SDK for browser (web) push

2. Configured push credentials:

   • iOS: APNS auth key (.p8, recommended) or certificate (.p12)
   • Android: Firebase service account JSON (FCM HTTP v1)
   • Web: a VAPID keypair, generated per web app with one click (see below)

3. Registered devices: Users must have granted push permission in your app or browser

Configuring Push Credentials

iOS (APNS)

1. Go to Settings → Apps → [Your App]
2. Open the app's push configuration
3. In the iOS (APNS) section, choose an Authentication Method:
   • Token-based (recommended): paste your Auth Key (.p8) content and enter the Key ID and Team ID
   • Certificate-based: upload your .p12 certificate file and enter its password
4. Select environment:
   • Development: For testing with development builds
   • Production: For App Store builds
5. Save the configuration

Getting APNS Credentials

Generate APNS certificates and auth keys in your Apple Developer Account.

Android (FCM)

1. Go to Settings → Apps → [Your App]
2. Open the app's push configuration
3. In the Android (FCM) section, click Upload service account JSON and provide your Firebase service account file (Joryio sends via the FCM HTTP v1 API):
   • Generate it in Firebase Console → Project Settings → Service accounts → Generate new private key
4. Enter your Sender ID (Firebase Console → Project Settings → Cloud Messaging)
5. Save the configuration

Firebase Setup

Follow the Firebase setup guide to create a Firebase project. Legacy "server keys" are not used - only the service account JSON.

Web (Browser Push)

Web push is configured per web app (each web app is a brand/site with its own keypair), alongside the mobile config:

1. Go to Settings → Apps → [Your Web App]
2. Navigate to the Push tab
3. In the Web Push (Browser) section, click Enable Web Push
   • This generates a VAPID keypair stored on that web app - there are no keys to copy or paste
4. Host the service worker on your site and trigger the opt-in from a user gesture (the section shows the exact one-line snippet and call)

One keypair per web app

Because each web app has its own VAPID keypair, two websites (whether in separate workspaces or two web apps in one workspace) each have their own browser subscribers. Regenerating keys invalidates that app's existing subscriptions, so users must re-opt-in.

Creating a Push Campaign

1. Navigate to Campaigns

Go to Campaigns → Create Campaign and select Push Notification.

2. Campaign Details

Name: Give your campaign a descriptive name

Example: "Weekend Sale - 20% Off"

Description (optional): Add internal notes about the campaign

Target app: pick the mobile app (APNS/FCM) the push goes to. If your workspace has 2 or more web apps with web push enabled, a Web App picker also appears - choose one site, or leave it on All web apps to reach every site's browser subscribers. (With a single web app it's automatic; the picker stays hidden.)

3. Target Audience

Select which users should receive the push notification:

Segment-Based

Choose a pre-defined segment:

• "Active Users (Last 7 Days)"
• "Premium Subscribers"
• "Cart Abandoners"

Learn more about creating segments

Behavior-Based

Target users based on specific actions:

• Event: "Abandoned Cart"
• Filter: Cart value > $50
• Time window: Last 24 hours

4. Message Content

Notification Title

Example: "Your cart is waiting!"

Title Best Practices

• Keep it under 50 characters
• Use emojis sparingly (1-2 max)
• Create urgency when appropriate
• Personalize with user data

Notification Body

Example: "Complete your purchase now and save 20% with code SAVE20. Offer ends tonight!"

Body Best Practices

• Keep under 120 characters - Chrome's truncation point and the safest cross-platform value (iOS allows 178, Android 240, but staying under 120 displays cleanly everywhere).
• Include a clear call-to-action
• Add time-sensitive information
• Personalize with liquid templates

Title length

Keep titles under 50 characters. The compose step shows a live counter with per-platform limits in a tooltip (iOS 50, Android 65, Chrome ~50).

Live preview (iOS / Android / Web)

The campaign editor has a sticky live preview alongside the compose form. Toggle between iOS lock-screen, Android heads-up, and a Chrome desktop toast - the preview updates as you type so you can see how the title and body wrap on each platform before sending.

URL or scheme (Optional)

Where the user lands when they tap the notification:

Format	Works on
https://acme.com/product/12345	All platforms (web, iOS, Android). Recommended default.
acme://product/12345	iOS / Android apps only - requires URL-scheme handling in your app.

Helper line in the campaign editor: "https:// works on all platforms. acme:// schemes only resolve inside your iOS / Android apps."

Image (Optional)

Attach an image (jpeg / png) shown alongside the notification. Browse the media library or paste a URL.

Action buttons (cross-platform)

Add up to 2 cross-platform action buttons. Each button has a label and a value (https://… URL or action:dismiss for in-app handlers):

• Button 1: "Track order" → https://acme.com/track/{{ event.order_id }}
• Button 2: "Talk to support" → action:dismiss

Per-platform max counts: Web 2 · iOS 4 · Android 3. The campaign UI shows 2 of 2 buttons used. Web shows up to 2 · iOS up to 4 · Android up to 3.

Group key

A key that lets new pushes replace the previous one instead of stacking when they share the same key. The same concept exists everywhere with different names - Web tag, Android collapse_key, iOS apns-collapse-id - and the field maps to all three. Useful for things like a single running "out for delivery" notification per user instead of five.

Mobile app behavior (iOS · Android only)

Setting	Description
Sound	Default or Silent. App-only.
Badge increment	Number to add to the iOS app icon badge.

Web behavior (Web only)

Setting	Description
Keep on screen until dismissed	Sets requireInteraction: true on the Web Push API. By default browser notifications auto-dismiss after a few seconds. Mobile pushes already stay until tapped.
Web site name	Shown in the Chrome toast header next to the site favicon.

5. Personalization with Liquid

Use Liquid templates to personalize messages:

Hi {{user.firstName}},

Your {{cart.itemCount}} items are waiting!
Cart total: ${{cart.total}}

Complete your purchase now and save 20%.

Available Variables:

• {{user.firstName}}, {{user.lastName}}
• {{user.email}}
• Custom attributes: {{user.plan}}, {{user.city}}
• Event properties from trigger

Learn more about Liquid templates

6. Scheduling

Choose when to send your push notification:

Send Immediately

Send as soon as the campaign is activated.

Scheduled Send

Send at a specific date and time:

• Date: 2024-01-20
• Time: 10:00 AM
• Timezone: America/New_York

Behavior-Triggered

Send when users perform specific actions:

• Trigger: "Abandoned Cart"
• Re-entry control: every time / once per user / cooldown between sends
• Active window: optional start and end dates for the trigger

Time-of-day limits ("don't push at 3 AM") are a workspace-level setting - configure per-channel quiet windows under Settings → Quiet Time.

Best Times to Send

• Morning (8-10 AM): High open rates
• Lunch (12-1 PM): Good engagement
• Evening (7-9 PM): Peak mobile usage
• Avoid: Late night (11 PM - 6 AM)

7. Frequency Capping

How often users can receive push notifications is governed by your workspace Touching Rules (Settings → Touching Rules), not per campaign:

• A per-channel rule for push - max messages per day / week / month (default: 10 per day), optionally scoped by tags
• An optional cross-channel ceiling across all channels

For genuinely critical sends, a campaign can enable bypass frequency limits in the Delivery step's advanced options.

Respect User Experience

Over-sending push notifications can lead to:

• Users disabling notifications
• App uninstalls
• Negative brand perception

Follow platform guidelines:

• iOS: Be respectful and relevant
• Android: Respect user preferences

8. A/B Testing

Test different message variations:

Variant A (50%)

• Title: "Your cart is waiting!"
• Body: "Complete your purchase and save 20%"

Variant B (50%)

• Title: "Don't miss out! Limited time offer"
• Body: "20% off your cart - expires in 6 hours"

Joryio automatically assigns users to variants and tracks performance.

9. Conversion Tracking

Define what counts as a conversion on the Conversion step:

• Primary Conversion: e.g. "Order Completed" (curated common events - including "Tapped push notification" - plus your custom events)
• Attribution Window: 24h / 72h / 7 days (default) / 14 days / 30 days
• Attribution Model: first touch / last touch (default) / linear

With the defaults, this tracks how many users complete a purchase within 7 days of receiving the push notification.

Platform-Specific Features

How the shared compose fields land on each platform:

iOS

• Image: delivered as a rich notification attachment (shown when the user expands the notification)
• Badge increment: adds the number you set to the app icon badge
• Sound: Default or Silent
• Group key: maps to apns-collapse-id - a new push replaces the previous one with the same key

Android

• Image: shown as a big-picture style expanded image
• Group key: maps to collapse_key
• Action buttons: up to 3 shown

Web

• Keep on screen until dismissed: sets requireInteraction so the toast doesn't auto-dismiss
• Web site name: shown in the browser toast header
• Group key: maps to the Web Notification tag
• Action buttons: up to 2 shown

Testing Your Campaign

1. Test Mode

Before activating, test your campaign:

1. Click Send test push on your variant
2. Pick a Random user or search for an existing user - the test goes to that user's registered devices, and personalization resolves against their data (custom users aren't available since they have no registered device)
3. Send the test

2. Verify Delivery

Check that the notification:

• Appears on device
• Shows correct title and body
• Opens correct screen when tapped
• Displays images/media properly
• Action buttons work

3. Review Analytics

After sending tests, verify:

• Device registered successfully
• Token valid and active
• No delivery errors

Monitoring Performance

Real-Time Metrics

Track campaign performance in real-time:

Metric	Description
Sent	Total notifications sent
Delivered	Successfully delivered to devices
Opened	Users who tapped the notification
Conversions	Users who completed conversion event
Failures	Delivery failures (invalid tokens, etc.)

Delivery Stats

• Delivery Rate: Delivered / Sent
• Open Rate: Opened / Delivered
• Conversion Rate: Conversions / Opened

Performance by Platform

Compare iOS vs Android performance:

• Open rates
• Conversion rates
• Best performing variants

Performance by Variant

For A/B tests, see which variant performed better:

• Variant A: 12.5% open rate, 3.2% conversion
• Variant B: 15.8% open rate, 4.1% conversion - winner

Best Practices

1. Get Permission Thoughtfully

Request push permission at the right time:

• After user sees value in your app
• With context: "Get notified when your order ships"
• Immediately on first launch

2. Segment Your Audience

Don't blast everyone:

• Target based on behavior
• Personalize based on preferences
• Respect user opt-outs

3. Write Compelling Copy

• Clear value: What's in it for the user?
• Create urgency: "24 hours left"
• Personalize: Use their name or data
• Strong CTA: "Shop Now", "Claim Offer"

4. Timing Matters

Send at optimal times:

• Consider user timezone
• Respect quiet hours
• Test different send times

5. Don't Over-Send

Respect frequency caps:

• Maximum 3-5 per week
• Minimum 4-hour gaps
• Let users control frequency

6. Test Everything

Before launching:

• Test on real devices
• Verify deep links work
• Check on different OS versions
• Test all A/B variants

7. Monitor & Optimize

Continuously improve:

• Track open and conversion rates
• A/B test message variations
• Remove invalid tokens
• Learn from top performers

Troubleshooting

Notifications Not Sending

Check:

1. Push credentials configured correctly
2. Users granted push permission
3. Device tokens registered successfully
4. Campaign is activated (not draft)

Low Delivery Rates

Common Causes:

• Invalid or expired device tokens
• Users uninstalled app
• Users disabled push permission
• Certificate expired (iOS)

Solution:

• Regularly clean invalid tokens
• Re-prompt users who disabled notifications
• Monitor certificate expiration dates

Low Open Rates

Possible Issues:

• Poor message copy
• Not relevant to audience
• Sent at wrong time
• Over-sending (notification fatigue)

Solutions:

• Improve copy and personalization
• Better audience targeting
• Optimize send times
• Implement frequency capping

Push Notification Limits

Platform limits imposed by Apple and Google:

iOS (APNS)

• Payload size: 4 KB maximum

Android (FCM)

• Payload size: 4 KB maximum
• TTL: 4 weeks maximum

Next Steps

• In-App Campaigns - Create in-app messages
• iOS SDK Setup - Integrate iOS push
• Android SDK Setup - Integrate Android push
• A/B Testing - Optimize your campaigns