Uninstall Tracking - (APNS) Apple Push Notification Service

Follow
Avatar
Jared Ornstead
Updated

Apple Push Notification Service (APNs) Setup Guide

Configure Apple Push Notification Service certificates and provisioning profiles to enable push notification delivery and uninstall tracking for iOS apps using Singular SDK.

Overview

Prerequisites

Enable APNs push notifications by creating SSL certificates and provisioning profiles in Apple Developer Member Center.

Required Components:

  • SSL Certificate: Associated with App ID configured for Push Notifications
  • Provisioning Profile: Authorizes devices to run app during development and testing
  • Apple Developer Account: Active membership required for certificate creation
  • Mac Computer: Required for Keychain Access and certificate generation

Apple Developer Portal: All certificate and profile management occurs in the Apple Developer Member Center. Ensure you have appropriate permissions in your organization's developer team.

Certificate Types

Apple provides two types of APNs SSL certificates for different environments.

Certificate Type Environment Use Case
Development SSL Certificate Sandbox Internal testing and development builds
Production SSL Certificate Production App Store releases and TestFlight builds

Environment Matching Critical: Apps must use certificates matching their build environment. Production apps with development certificates will fail to receive push notifications.

Step 1: Generate Certificate Signing Request

Create a Certificate Signing Request (CSR) file on your Mac to authenticate SSL certificate creation.

Create CSR File

Using Keychain Access

Generate CSR through Keychain Access application on macOS.

  1. Open Keychain Access: Navigate to Applications → Utilities → Keychain Access, or use Spotlight search (Cmd+Space)
  2. Access Certificate Assistant: In menu bar, select Keychain Access → Certificate Assistant → Request a Certificate From a Certificate Authority...
  3. Enter User Information:
    • User Email Address: Enter your email address (used in Apple Developer account)
    • Common Name: Enter descriptive name (e.g., "YourCompany APNs Certificate")
    • CA Email Address: Leave blank
  4. Select Request Type: Choose "Saved to disk" option (required for manual certificate creation)
  5. Save CSR File: Click Continue and save the .certSigningRequest file to a memorable location on your Mac

Certificate Signing Request Creation

Private Key Storage: Keychain Access automatically generates and stores a private key when creating the CSR. This private key pairs with the SSL certificate you'll download from Apple later.

Step 2: Create or Configure App ID

Create a new App ID or configure existing App ID to enable Push Notification capability.

Understanding App IDs

App ID Structure

An App ID uniquely identifies your iOS application and must be an explicit identifier (not wildcard) to support Push Notifications.

Format: Reverse domain notation (e.g., com.yourcompany.appname)

Explicit App ID Required: Wildcard App IDs (containing *) cannot use Push Notifications. If you have an existing wildcard App ID, create a new explicit App ID for push-enabled apps.

Create New App ID

App ID Configuration Steps

Create a new App ID in Apple Developer portal with Push Notifications enabled.

  1. Access Developer Portal: Navigate to Apple Developer Member Center and sign in
  2. Open Certificates & Identifiers: Select "Certificates, Identifiers & Profiles"
  3. Navigate to Identifiers: In left sidebar, choose "Identifiers"
  4. Select Platform: In top-left dropdown, select "iOS Apps" (or "iOS, tvOS, watchOS" in newer interface)
  5. Create Identifier: Click the "+" button to create new App ID

Create App ID Button

Configure App ID Details

Fill in App ID information and enable Push Notifications capability.

  1. Select Type: Choose "App IDs" (not App Clips)
  2. Select Bundle Type: Choose "App" as the type
  3. Enter Description: Provide meaningful name (e.g., "YourApp Production")
  4. Set Bundle ID: In App ID Prefix section, use default Team ID
  5. Enter Explicit Bundle ID: In Bundle ID field, enter your app's identifier exactly as it appears in Xcode (e.g., com.yourcompany.appname)

Bundle ID Configuration

Bundle ID Matching: The Bundle ID value must exactly match the identifier in your app's Info.plist file and Xcode project settings. Case sensitivity matters.

Enable Push Notifications

Activate Push Notifications capability in App Services section.

  1. Scroll to Capabilities: Locate "App Services" section
  2. Enable Push Notifications: Check the "Push Notifications" checkbox
  3. Review Configuration: Click Continue and verify settings
  4. Confirm App ID: Verify the Identifier shows your Bundle ID correctly
  5. Check Status: Confirm Push Notifications shows as "Configurable"
  6. Register App ID: Click Submit to create the App ID

Enable Push Notifications

Step 3: Configure Push Notification Certificate

Generate SSL certificates for Push Notifications to enable APNs communication with your app.

Access App ID Settings

Edit App ID Configuration

Open App ID settings to create SSL certificates for development and production environments.

  1. Navigate to Identifiers: In Apple Developer portal, go to Certificates, Identifiers & Profiles → Identifiers
  2. Select App ID: Click on the App ID you created or want to configure
  3. Edit Configuration: Click "Edit" button (or App ID opens directly in edit mode)
  4. Locate Push Notifications: Scroll to "Push Notifications" section in capabilities list

Edit App ID

Create Development SSL Certificate

Generate Development Certificate

Create development certificate for testing push notifications during development.

  1. Start Certificate Creation: In Push Notifications section, click "Create Certificate..." under Development SSL Certificate
  2. Review Instructions: Read the "About Creating a Certificate Signing Request (CSR)" information
  3. Continue: Click Continue button
  4. Upload CSR: Click "Choose File..." and select the .certSigningRequest file you created in Step 1
  5. Generate: Click Continue (or Generate) to create the certificate

Push Notifications Certificate Options

Upload CSR

Download and Install Certificate

Download SSL certificate and install it in your Mac Keychain for use with push notifications.

  1. Download Certificate: Click "Download" button to save .cer file to your Mac
  2. Complete Process: Click "Done" to close certificate creation flow
  3. Install Certificate: Locate downloaded .cer file and double-click to add it to Keychain
  4. Verify Installation: Open Keychain Access and navigate to "My Certificates" category
  5. Locate Certificate: Find "Apple Development iOS Push Services: your.bundle.id" certificate with associated private key

Certificate Pairing: The downloaded certificate automatically pairs with the private key generated during CSR creation. Both must be present in Keychain for push notifications to work.

Export Certificate as .p12

Generate P12 File

Export certificate and private key as .p12 file for upload to push notification services (like Singular).

  1. Open Keychain Access: Navigate to "My Certificates" category
  2. Expand Certificate: Click disclosure triangle next to "Apple Development iOS Push Services" certificate to reveal private key
  3. Select Both Items: Hold Command key and click to select both certificate and private key
  4. Export: Right-click selection and choose "Export 2 items..."
  5. Name File: Save with descriptive name (e.g., "YourApp_Development_APNs.p12")
  6. Choose Format: Ensure "Personal Information Exchange (.p12)" is selected as file format
  7. Set Password: Enter strong password to protect the .p12 file
  8. Confirm Export: Click OK and enter Mac login password if prompted

Security Warning: The .p12 file contains your private key and certificate. Store it securely and never commit it to public repositories. Remember the password—it cannot be recovered.

Create Production SSL Certificate

Production Certificate Generation

Repeat the certificate creation process for Production SSL Certificate required for App Store releases.

  1. Return to App ID Settings: Navigate back to your App ID configuration in Apple Developer portal
  2. Production Certificate: In Push Notifications section, click "Create Certificate..." under Production SSL Certificate
  3. Follow Same Process: Upload CSR, generate certificate, download, and install in Keychain
  4. Export Production P12: Export as .p12 with descriptive name (e.g., "YourApp_Production_APNs.p12")
  5. Secure Storage: Store production certificate securely separate from development certificate

Production Certificate Required: Apps submitted to App Store and distributed via TestFlight MUST use Production SSL certificates. Development certificates will fail in production environment.

Step 4: Create Provisioning Profile

Generate provisioning profiles to authorize devices to run your app during development and testing phases.

Understanding Provisioning Profiles

Profile Types

Provisioning profiles link your App ID, certificates, and registered devices to enable app installation and testing.

Profile Type Purpose Device Limit
iOS App Development Internal testing on registered devices Up to 100 devices per profile
Ad Hoc Distribution to testers outside development team Up to 100 devices per profile
App Store App Store distribution and TestFlight Unlimited (all devices)

Create Development Profile

Development Profile Setup

Create iOS App Development provisioning profile for push notification testing.

  1. Access Provisioning Profiles: In Apple Developer portal, navigate to Certificates, Identifiers & Profiles → Profiles
  2. Create New Profile: Click "+" button to start profile creation
  3. Select Type: Choose "iOS App Development" under Development section
  4. Continue: Click Continue button
  5. Select App ID: In dropdown menu, choose the App ID configured for Push Notifications
  6. Continue: Click Continue button

Configure Profile Details

Select certificates, devices, and name the provisioning profile.

  1. Select Certificate: Check the iOS Development certificate associated with your App ID
  2. Continue: Click Continue button
  3. Select Devices: Check all devices where you want to test push notifications (must be pre-registered in Devices section)
  4. Continue: Click Continue button
  5. Name Profile: Enter descriptive name (e.g., "YourApp Development Push Testing")
  6. Generate Profile: Click Generate button

Device Registration: Test devices must be registered in Apple Developer portal before they can be added to provisioning profiles. Register devices by UDID in Devices section.

Install Provisioning Profile

Download and install the provisioning profile for use in Xcode.

  1. Download Profile: Click Download button to save .mobileprovision file
  2. Install Profile: Double-click downloaded .mobileprovision file to add it to Xcode
  3. Verify Installation: Open Xcode → Preferences → Accounts → View Details to confirm profile appears
  4. Select in Project: In Xcode project settings, select the provisioning profile under Signing & Capabilities

Profile Expiration: Provisioning profiles expire after one year. Renew expired profiles in Apple Developer portal and download new .mobileprovision files.

Verification and Testing

Verify APNs configuration is correct by testing push notification delivery to development devices.

Configuration Checklist

Pre-Testing Verification

Confirm all components are correctly configured before testing push notifications.

  • App ID: Explicit App ID with Push Notifications capability enabled
  • SSL Certificates: Development and Production certificates created and exported as .p12
  • Provisioning Profile: Development profile installed in Xcode with correct App ID and devices
  • Bundle ID Match: Xcode project Bundle ID exactly matches App ID identifier
  • Capabilities: Push Notifications capability enabled in Xcode Signing & Capabilities
  • Keychain: Certificates with private keys present in Mac Keychain "My Certificates"

Testing Push Notifications

Test Procedure

Send test push notification to verify APNs configuration.

  1. Build and Install: Build app with development provisioning profile and install on test device
  2. Request Permissions: Launch app and grant push notification permissions when prompted
  3. Register Device Token: Verify app receives APNs device token in console logs
  4. Send Test Notification: Use APNs testing tool or push service to send test notification
  5. Verify Delivery: Confirm notification appears on device

Common Issues

Issue Cause Solution
No device token received Push Notifications not enabled in capabilities Enable Push Notifications in Xcode Signing & Capabilities tab
Certificate not found error Private key missing from Keychain Re-export certificate including private key from original Mac that created CSR
Push notifications not delivered Wrong environment (dev vs prod) Verify certificate type matches build configuration
Provisioning profile invalid Profile expired or devices not registered Renew provisioning profile and ensure devices are registered
Bundle ID mismatch Xcode Bundle ID doesn't match App ID Update Bundle ID in Xcode to exactly match App ID identifier

Testing Tools: Use Apple's Push Notification Console in Xcode or third-party tools like Pusher, Knuff, or curl commands to send test notifications during development.

Next Steps

With APNs configured, integrate push notification handling in your app and configure Singular for uninstall tracking.

Integration Guides

Complete Your Setup

  • iOS Push Implementation: Implement APNs registration and notification handling in your iOS app code
  • Singular SDK Integration: Follow the Singular iOS SDK Implementation Guide to enable uninstall tracking
  • Upload Certificate to Singular: Upload your .p12 certificate to Singular's app configuration for uninstall tracking
  • Test Uninstall Tracking: Verify uninstall detection works correctly before production release

Production Deployment

App Store Submission Requirements:

  • Production Certificate: Use Production SSL certificate for App Store builds
  • App Store Profile: Create and use App Store Distribution provisioning profile
  • Code Signing: Ensure correct certificate and profile selected in Xcode Archive settings
  • TestFlight: TestFlight builds use Production environment—test with Production certificate