Create and send push notifications

Learn how to create push notifications for mobile apps with Experience Platform Mobile SDK and Journey Optimizer.

Journey Optimizer allows you to create journeys and send messages to targeted audiences. Before you send push notifications with Journey Optimizer, you must ensure that the proper configurations and integrations are in place. To understand the Push Notifications data flow in Journey Optimizer, refer to the documentation.

Architecture

NOTE
This lesson is optional and only applies to Journey Optimizer users looking to send push notifications.

Prerequisites

  • Successfully built and run the app with SDKs installed and configured.

  • Set up the app for Adobe Experience Platform.

  • Access to Journey Optimizer and sufficient permissions as described here. Also you need sufficient permission to the following Journey Optimizer features.

    • Create an app surface.
    • Create a journey.
    • Create a message.
    • Create message presets.
  • Paid Apple developer account with sufficient access to create certificates, identifiers, and keys.

  • Physical iOS device or simulator for testing.

Learning objectives

In this lesson, you will

  • Register App ID with the Apple Push Notification service (APNs).
  • Create an App Surface in Journey Optimizer.
  • Update your schema to include push messaging fields.
  • Install and configure the Journey Optimizer tag extension.
  • Update your app to register the Journey Optimizer tag extension.
  • Validate setup in Assurance.
  • Send a test message from Assurance
  • Define your own push notification event, journey, and experience in Journey Optimizer.
  • Send your own push notification from within the app.

Setup

TIP
If you have set up your environment already as part of the Journey Optimizer in-app messaging lesson, you might already have performed some of the steps in this setup section.

Register App ID with APNs

The following steps are not Adobe Experience Cloud-specific and are designed to guide you through APNs configuration.

Create a private key

  1. In the Apple developer portal, navigate to Keys.

  2. To create a key, select +.
    create new key

  3. Provide a Key Name.

  4. Select the Apple Push Notification service (APNs) checkbox.

  5. Select Continue.
    configure new key

  6. Review the configuration and select Register.

  7. Download the .p8 private key. It is used in the App Surface configuration later in this lesson.

  8. Make note of the Key ID. It is used in the App Surface configuration.

  9. Make note of the Team ID. It is used in the App Surface configuration.
    Key Details

Additional documentation can be found here.

Add an app surface in Data Collection

  1. From the Data Collection interface, select App Surfaces in the left-hand panel.

  2. To create a configuration, select Create App Surface.
    app surface home

  3. Enter a Name for the configuration, for example Luma App Tutorial .

  4. From Mobile Application Configuration, select Apple iOS.

  5. Enter the mobile app Bundle Id in the App ID (iOS Bundle ID) field. For example, com.adobe.luma.tutorial.swiftui.

  6. Switch on the Push Credentials toggle to add your credentials.

  7. Drag and drop your .p8 Apple Push Notification Authentication Key file.

  8. Provide the Key ID, a 10-character string assigned during the creation of p8 auth key. It can be found under the Keys tab in the Certificates, Identifiers and Profiles page of the Apple Developer portal pages. See also Create a private key.

  9. Provide the Team ID. The Team ID is a value which can be found under the Membership tab or at the top of the Apple Developer portal page. See also Create a private key.

  10. Select Save.

    app surface configuration

Update datastream configuration

To ensure data send from your mobile app to the Edge Network is forwarded to Journey Optimizer, update your Experience Edge configuration .

  1. In the Data Collection UI, select Datastreams, and select your datastream, for example Luma Mobile App.

  2. Select More for Experience Platform and select Edit Edit from the context menu.

  3. In the Datastreams > Folder > Adobe Experience Platform screen:

    1. If not already selected, select AJO Push Profile Dataset from Profile Dataset. This profile dataset is required when using the MobileCore.setPushIdentifier API call (see Register device token for push notifications) which ensures the unique identifier for push notifications (a.k.a. push identifier) is stored as part of the profile of the user.

    2. Adobe Journey Optimizer is selected. See Adobe Experience Platform settings for more information.

    3. To save your datastream configuration, select Save.

    AEP datastream configuration

Install Journey Optimizer tags extension

For your app to work with Journey Optimizer, you must update your tag property.

  1. Navigate to Tags > Extensions > Catalog,

  2. Open your property, for example Luma Mobile App Tutorial.

  3. Select Catalog.

  4. Search for the Adobe Journey Optimizer extension.

  5. Install the extension.

  6. In the Install Extension dialog

    1. Select an environment, for example Development.
    2. Select the AJO Push Tracking Experience Event Dataset dataset from the Event Dataset list.
    3. Select Save to Library and Build.
      AJO extension settings
NOTE
If you don’t see AJO Push Tracking Experience Event Dataset as an option, contact customer care.

Validate setup with Assurance

  1. Review the setup instructions section to connect your simulator or device to Assurance.

  2. In the Assurance UI, select Configure.
    configure click

  3. Select Plus next to Push Debug.

  4. Select Save.
    save

  5. Select Push Debug from the left navigation.

  6. Select the Validate Setup tab.

  7. Select your device from the Client list.

  8. Confirm that you aren’t getting any errors.
    validate

  9. Select the Send Test Push tab.

  10. (optional) Change the default details for Title and Body

  11. Select Bug Send Test Push Notification.

  12. Check the Test Results.

  13. You should see the test push notification appear in your app.

Signing

Signing the Luma app is needed to send push notifications and requires a paid Apple developer account.

To update the signing for your app:

  1. Go to your app in Xcode.

  2. Select Luma in the Project navigator.

  3. Select the Luma target.

  4. Select the Signing & Capabilities tab.

  5. Configure Automatic manage signing, Team, and Bundle Identifier, or use your specific Apple development provisioning details.

    note important
    IMPORTANT
    Ensure you use a unique bundle identifier and replace the com.adobe.luma.tutorial.swiftui bundle identifier, as each bundle identifier must be unique. Typically, you use a reverse-DNS format for bundle ID strings, like com.organization.brand.uniqueidentifier. The Finished version of this tutorial, for example, uses com.adobe.luma.tutorial.swiftui.
    img-md
    modal-image
    Xcode signing capabilities

Add push notification capabilities to your app

IMPORTANT
To implement and test push notification in an iOS app, you must have a paid Apple developer account. If you do not have a paid Apple developer account, you can skip the remainder of this lesson.
  1. In Xcode, select Luma from the TARGETS list, select the Signing & Capabilities tab, select the + Capability button, then select Push Notifications. This enables your app to receive push notifications.

  2. Next, you must add a Notification Extension to the app. Go back to the General tab and select the + icon at the bottom of the TARGETS section.

  3. You are prompted to select the template for your new target. Select Notification Service Extension then select Next.

  4. In the next window, use NotificationExtension as the name of the extension and click the Finish button.

You should now have a push notification extension added to your app, similar to the screen below.

Pusn nofitications extension

Implement Journey Optimizer in the app

As discussed in previous lessons, installing a mobile tag extension only provides the configuration. Next you must install and register the Messaging SDK. If these steps aren’t clear, review the Install SDKs section.

NOTE
If you completed the Install SDKs section, then the SDK is already installed and you can skip this step.
  1. In Xcode, ensure that AEP Messaging is added to the list of packages in Package Dependencies. See Swift Package Manager.

  2. Navigate to Luma > Luma > AppDelegate in the Xcode Project navigator.

  3. Ensure AEPMessaging is part of your list of imports.

    import AEPMessaging

  4. Ensure Messaging.self is part of the array of extensions that you are registering.

    code language-swift
    let extensions = [
        AEPIdentity.Identity.self,
        Lifecycle.self,
        Signal.self,
        Edge.self,
        AEPEdgeIdentity.Identity.self,
        Consent.self,
        UserProfile.self,
        Places.self,
        Messaging.self,
        Optimize.self,
        Assurance.self
    ]
    

Register device token for push notifications

  1. Add the MobileCore.setPushIdentifier API to the func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) function.

    code language-swift
    // Send push token to Mobile SDK
    MobileCore.setPushIdentifier(deviceToken)
    

    This function retrieves the device token unique to the device that the app is installed on. Then sets the token for push notification delivery using the configuration that you have set up and which relies on Apple’s Push Notification service (APNs).

IMPORTANT
The MobileCore.updateConfigurationWith(configDict: ["messaging.useSandbox": true]) determines whether push notifications are using an APNs sandbox or production server for sending push notifications. When testing your app in the simulator or on a device, ensure the messaging.useSandbox is set to true so you receive push notifications. When deploying your app for production ot test using Apple’s Testflight, ensure you set messaging.useSandbox to false otherwise your production app will not be able to receive push notifications.

Create your own push notification

To create your own push notification, you must define an event in Journey Optimizer that triggers a journey that takes care of sending a push notification.

Update your schema

You are going to define a new event type, not available yet as part of the list of events that are defined in your schema. You use this event type later when triggering push notifications.

  1. In the Journey Optimizer UI, select Schemas from the left rail.

  2. Select Browse in the tab bar.

  3. Select your schema, for example Luma Mobile App Event Schema to open it.

  4. In the Schema editor:

    1. Select the eventType field.
    2. In the Field properties pane, scroll down to see the list of possible values for event type. Select Add row, and add application.test as the VALUE and Test event for push notification as the DISPLAY NAME.
    3. Select Apply.
    4. Select Save.
      Add value to event types

Define an event

Events in Journey Optimizer allow you to trigger your journeys unitarily to send messages, for example push notifications. See About events for more information.

  1. In the Journey Optimizer UI, select Configurations from the left rail.

  2. In the Dashboard screen, select the Manage button in the Events tile.

  3. In the Events screen, select Create Event.

  4. In the Edit event event1 pane:

    1. Enter LumaTestEvent as the Name of the event.

    2. Provide a Description, for example Test event to trigger push notifications in Luma app.

    3. Select the mobile app experience event schema that you created earlier in Create an XDM schema from the Schema list, for example Luma Mobile App Event Schema v.1.

    4. Select Edit next to the Fields list.

      Edit event step 1

      In the Fields dialog, ensure that the following fields are selected (on top of the default fields that are always selected (_id, id, and timestamp)). You can toggle, using the dropdown list, between Selected, All and Primary or use the Search field.

      • Application Identified (id),
      • Event Type (eventType),
      • Primary (primary).

      Edit event fields

      Then select Ok.

    5. Select Edit next to the Event id condition field.

      1. In the Add an event id condition dialog, drag and drop Event Type (eventType) on to Drag and drop an element here.
      2. In the popover, scroll to the bottom and select application.test (which is the event type you added earlier to the list of event types as part of Update your schema). Then scroll up to the top and select Ok.
      3. Select Ok to save the condition.
        Edit event condition
    6. Select ECID (ECID) from the Namespace list. Automatically the Profile identifier field is populated with The id of the first element of the key ECID for the map identityMap.

    7. Select Save.
      Edit event step 2

You just created an event configuration that is based on the mobile app experience events schema you created earlier as part of this tutorial. This event configuration will filter incoming experience events using your specific event type (application.test), so only events with that specific type, initiated from your mobile app, will trigger the journey you build in the next step. In a real-world scenario you might want to send push notifications from an external service, however the same concepts apply: from the external application send an experience event into Experience Platform that has specific fields you can use to apply conditions on before these events trigger a journey.

Create the journey

Your next step is to create the journey that triggers the sending of the push notification when receiving the appropriate event.

  1. In the Journey Optimizer UI, select Journeys from the left rail.

  2. Select Create Journey.

  3. In the Journey Properties panel:

    1. Enter a Name for the journey, for example Luma - Test Push Notification Journey.
    2. Enter a Description for the journey, for example Journey for test push notifications in Luma mobile app.
    3. Ensure Allow re-entrance is selected and set Re-entrance wait period to 30 Seconds.
    4. Select Ok.
      Journey properties
  4. Back at the journey canvas, from the EVENTS, drag and drop your Event LumaTestEvent on the canvas where it shows Select an entry event or a read audience activity.

    • In the Events: LumaTestEvent panel, enter a Label, for example Luma Test Event.
  5. From the ACTIONS dropdown, drag and drop Push Push on the Add appearing to the right of your LumaTestEvent activity. In the Actions: Push pane:

    1. Provide a Label, for example Luma Test Push Notification, provide a Description, for example Test push notification for Luma mobile app, select Transactional from the Category list and select Luma from the Push surface.

    2. Select Edit Edit content to start editing the actual push notification.
      Push properties

      In the Push Notification editor:

      1. Enter a Title, for example Luma Test Push Notification and enter a Body, for example Test push notification for Luma mobile app.
      2. Optionally, you can enter a link to an image (.png or .jpg) in Add media. If you do so, the image will be part of the push notification.
      3. To save and leave the editor, select Chevron left .
        Push editor
    3. To save and finish the push notification definition, select Ok.

  6. Your journey should look like below. Select Publish to publish and activate your journey.
    Finished journey

Trigger the push notification

You have all the ingredients in place to send a push notification. What remains is how to trigger this push notification. In essence, it is the same as you have seen before: simply send an experience event with the proper payload (as in Events).

This time the experience event you are about to send is not constructed building a simple XDM dictionary. You are going to use a struct representing a push notification payload. Defining a dedicated data type is an alternative way on how to implement constructing experience event payloads in your application.

  1. Navigate to Luma > Luma > Model > XDM > TestPushPayload in the Xcode Project navigator and inspect the code.

    code language-swift
    import Foundation
    
    // MARK: - TestPush
    struct TestPushPayload: Codable {
       let application: Application
       let eventType: String
    }
    
    // MARK: - Application
    struct Application: Codable {
       let id: String
    }
    

    The code is a representation of the following simple payload that you are going to send to trigger your test push notification journey

    code language-json
    {
       "eventType": string,
       "application" : [
           "id": string
       ]
    }
    
  2. Navigate to Luma > Luma > Utils > MobileSDK in the Xcode Project navigator and add the following code to func sendTestPushEvent(applicationId: String, eventType: String):

    code language-swift
    // Create payload and send experience event
    Task {
        let testPushPayload = TestPushPayload(
            application: Application(
                id: applicationId
            ),
            eventType: eventType
        )
        // send the final experience event
        await sendExperienceEvent(
            xdm: testPushPayload.asDictionary() ?? [:]
        )
    }
    

    This code creates a testPushPayload instance using the parameters provided to the function (applicationId and eventType) and then calls sendExperienceEvent while converting the payload to a dictionary. This code, this time, also takes the asynchronous aspects of calling the Adobe Experience Platform SDK into account by using Swift’s concurrency model based on await and async.

  3. Navigate to Luma > Luma > Views > General > ConfigView in the Xcode Project navigator. In the Push Notification Button definition, add the following code to send the test push notification experience event payload to trigger your journey whenever that button is tapped.

    code language-swift
    // Setting parameters and calling function to send push notification
    Task {
        let eventType = testPushEventType
        let applicationId = Bundle.main.bundleIdentifier ?? "No bundle id found"
        await MobileSDK.shared.sendTestPushEvent(applicationId: applicationId, eventType: eventType)
    }
    

Validate using your app

  1. Rebuild and run the app in the simulator or on a physical device from Xcode, using Play .

  2. Go to the Settings tab.

  3. Tap Push Notification. You see the push notification appear in your app.

Next steps

You should now have all the tools to handle push notifications in your app. For example, you could build a journey in Journey Optimizer that sends a welcome push notification when a user of the app logs in. Or a confirmation push notification when a user purchases a product in the app. Or enters the geofence of a location (as you will see in the Places lesson).

SUCCESS
You have now enabled the app for push notification using Journey Optimizer and the Journey Optimizer extension for the Experience Platform Mobile SDK.
Thank you for investing your time in learning about Adobe Experience Platform Mobile SDK. If you have questions, want to share general feedback, or have suggestions on future content, share them on this Experience League Community discussion post.

Next: Create and send in-app messages

recommendation-more-help
9fed61f5-c338-47ad-8005-0b89a5f4af8b