Catapush iOS Swift SDK Example

This project shows how Catapush iOS SDK can be integrated to receive Catapush messages and display them with a customizable bubble layout. For more information about Catapush platform check out the official website: Catapush - reliable push notification service.

Requirements

• iOS 15.0+
• Xcode 13.0+
• Swift 5.0+
• CocoaPods

This example uses the iOS 13+ Scene-based application lifecycle with both AppDelegate and SceneDelegate.

📱 Multi-Window Support: For apps requiring multi-scene support (multiple windows on iPad), see the Multi-Scene Integration Guide.

Usage

1. sudo gem install cocoapods

2. git clone https://github.com/Catapush/catapush-ios-swift-sdk-example.git

3. cd catapush-ios-swift-sdk-example

4. pod install

5. open catapush-ios-swift-sdk-example.xcworkspace

6. Get your App Key from Catapush Dashboard from the left menu in "Your APP" -> App details

7. Create the first user from "Your APP" -> User

8. Configure your App Key and user credentials in two files:

   AppDelegate.swift - Global configuration and push notification setup:

   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
       // Set your Catapush credentials
       Catapush.setAppKey("YOUR_APP_KEY")
       Catapush.setIdentifier("test", andPassword: "test")
   
       // Register for push notifications (must be called on AppDelegate)
       Catapush.registerUserNotification(self)
   
       application.applicationIconBadgeNumber = 0
       UNUserNotificationCenter.current().delegate = self
   
       return true
   }

   SceneDelegate.swift - UI setup and Catapush connection:

   func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
       guard let windowScene = (scene as? UIWindowScene) else { return }
   
       // Setup window
       window = UIWindow(windowScene: windowScene)
       let storyboard = UIStoryboard(name: "Main", bundle: nil)
       window?.rootViewController = storyboard.instantiateInitialViewController()
       window?.makeKeyAndVisible()
   
       // Setup Catapush delegates and start connection
       Catapush.setupCatapushStateDelegate(self, andMessagesDispatcherDelegate: self)
   
       var error: NSError?
       Catapush.start(&error)
   
       if let error = error {
           print("Error: \(error.localizedDescription)")
       }
   }

   Note: With the iOS 13+ Scene-based lifecycle, responsibilities are split between AppDelegate (app-level setup like push notifications) and SceneDelegate (UI setup and Catapush connection).

9. Set you Team under Signing & Capabilities and change the bundle it to a unique one.

10. Configure the App Groups

11. Create an Apple authentication key in order to be able to send push notifications and configure your Catapush application in the Catapush Dashboard

12. Run the app

13. Back to your Catapush Dashboard and send a test message from "Your APP" -> Send Push.

Certificate, App Id, Push Entitlements and App Groups

• Make sure your app has an explicit app id and push entitlements in Apple's Developer Portal.
• Create an Apple Push Notification Authentication Key and configure your Catapush applicaton hosted on Catapush servers.
• Create a specific App Group for the iOS Application and the Notification Service Extension.

Create and configure the authentication key

This section describes how to generate an authentication key for an App ID enabled for Push Notifications. If you have an existing key, you can use that key instead of generating a new one.

To create an authentication key:

1. In your Apple Developer Member Center, go to Certificates, Identifiers & Profiles, and select Keys.
2. Click the Add button (+) or click the "Create a key" button.

3) Enter a description for the APNs Auth Key. 4) Under Key Services, select the Apple Push Notifications service (APNs) checkbox, and click Continue.

5) Click Register and then download and save your key in a secure place. This is a one-time download, and the key cannot be retrieved later.

Once you have download it you have to configure your Catapush application.

1. Go to https://www.catapush.com/panel/apps/YOUR_APP_ID/platforms.
2. Click on iOS Token Based to enable it.
3. Fill iOS Team Id, iOS Key Id, iOS AuthKey and iOS Topic.

The iOS Team Id can be found here https://developer.apple.com/account/#/membership in "Membership Information" section.

The iOS Key Id can be retrieved here https://developer.apple.com/account/resources/authkeys/list, click on the key you have created and you can find it under "View Key Details" section.

The iOS AuthKey is the content of the key file.

Example:

-----BEGIN PRIVATE KEY-----
...........................
          AUTH_KEY
...........................
-----END PRIVATE KEY-----

The iOS Topic is the bundle identifier of your iOS application.

App Groups

Catapush need that the Notification Service Extension and the main application can share resources. In order to do that you have to create and enable a specific app group for both the application and the extension. The app and the extension must be in the same app group.

You should also add this information in the App plist and the Extension plist (group.example.group should match the one you used for example group.catapush.test in the screens):

    <key>Catapush</key>
    <dict>
        <key>AppGroup</key>
        <string>group.catapush.test</string>
    </dict>

UI appearance

You can easily configure the UI appearance by changing TextFont, Background color attributes.

You can add this code in AppDelegate.swift (application(_:didFinishLaunchingWithOptions:) method) or in SceneDelegate.swift (scene(_:willConnectTo:options:) method before makeKeyAndVisible()). For UI-related configuration, SceneDelegate is the more appropriate location.

    MessageCollectionViewCell.cornerRadius = 10
    MessageCollectionViewCell.borderColor = UIColor(white:0,alpha:0.2)
    MessageCollectionViewCell.borderWidth = 0.5
    MessageCollectionViewCell.textColor = UIColor.white
    MessageCollectionViewCell.backgroundColor = UIColor.lightGray
    MessageCollectionViewCell.textFont = UIFont(name:"HelveticaNeue",size:18)!
    MessageNavigationBar.barTintColor = UIColor.red
    MessageNavigationBar.titleTextAttributes = [
        NSAttributedString.Key.foregroundColor    : UIColor.green,
        NSAttributedString.Key.font        : UIFont(name:"HelveticaNeue-CondensedBlack", size:21.0)!];

The following code shows how to change the appearance of the message bubbles and the navigation bar:

// In AppDelegate.swift - application(_:didFinishLaunchingWithOptions:)
// OR in SceneDelegate.swift - scene(_:willConnectTo:options:) before makeKeyAndVisible()

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

     // ... your Catapush setup code ...

    MessageCollectionViewCell.cornerRadius = 2
    MessageCollectionViewCell.borderColor = UIColor(white:0,alpha:0.2)
    MessageCollectionViewCell.borderWidth = 0.5
    MessageCollectionViewCell.textColor = UIColor.white
    MessageCollectionViewCell.backgroundColor = UIColor.lightGray
        
    let shadow = NSShadow()
    shadow.shadowColor = UIColor(white:0,alpha:0.8)
    shadow.shadowOffset = CGSize(width: 0, height: 1)
    MessageNavigationBar.barTintColor = UIColor.red
    MessageNavigationBar.titleTextAttributes = [
        NSAttributedString.Key.foregroundColor: UIColor(red:245.0/255.0,green:245.0/255.0,blue:255.0/255.0,alpha:1),
        NSAttributedString.Key.font           : UIFont(name:"HelveticaNeue-CondensedBlack", size:21.0)!,
        NSAttributedString.Key.shadow         : shadow
    ]
    return true

}

Clipboard

Use Long tap to copy a text into clipboard.

Migration Notes

iOS 13+ Scene Support

This example app has been updated to use the iOS 13+ Scene-based lifecycl.

For Developers Using This as Reference

If you're integrating Catapush into an existing app:

• With SceneDelegate: Follow the split architecture shown in this example (AppDelegate + SceneDelegate)
• AppDelegate-only: Keep all Catapush setup in AppDelegate as before (legacy approach)

📱 Multi-Scene Support: If your app needs to support multiple windows simultaneously (primarily on iPad), see the comprehensive Multi-Scene Integration Guide for architecture patterns, implementation details, and best practices.

Migration Path from AppDelegate-only to SceneDelegate

If you're migrating an existing Catapush integration to use SceneDelegate:

Move to SceneDelegate:

• Catapush.setupCatapushStateDelegate() → SceneDelegate
• Catapush.start() → SceneDelegate
• Delegate conformances (CatapushDelegate, MessagesDispatchDelegate) → SceneDelegate
• Window setup → SceneDelegate
• Scene lifecycle calls (background/foreground) → SceneDelegate

Keep in AppDelegate:

• Catapush.setAppKey() (global configuration)
• Catapush.setIdentifier() (user credentials)
• Catapush.registerUserNotification(self)
• Push notification registration methods