SDK: React Native

Step 1: Import the PushSDK Library

Install the PushSDK using either your preferred package manager.

Yarn

yarn add @pushly/push-sdk-react-native

NPM

npm install --save @pushly/push-sdk-react-native

Autolinking is provided automatically if you are using React Native version 0.60 or greater.

Step 2: Android Setup

Step 2.1: Gradle

Update your gradle scripts with the required dependencies:

android/build.gradle

buildscript {
    ...
    dependencies {
        ...
        classpath 'com.google.gms:google-services:4.3.13'
    }
}

android/app/build.gradle

android {
    compileSdk 33
    ...

    defaultConfig {
        ...
        targetSdk 33
    }
}

apply plugin: 'com.google.gms.google-services'

Step 2.2: Google Services

Add your google-services.json file to android/app directory.

Step 3: iOS Setup

Step 3.1: Install Pods

Within your <project_root>/ios directory run: pod install

Step 3.2: Add Notification Service Extension

The Notification Service Extension is required to enable rich notifications that support images and custom actions.

Open XCode using your app's xcworkspace. Next, select File > New > Target and then select Notification Service Extension inside the iOS templates tab and click Next.

Enter "NotificationServiceExtension" for the Product Name and any other configuration details for your app extension and then click Finish but do not click activate on the subsequent dialog.

Click Cancel on the dialoging prompting you to activate the service extension so that you can set the deployment target once the modal is closed.

Make sure to set your deployment target to the same as your primary application target. Unless you have a specific reason not to, you should set the Deployment Target to be iOS 11 which is the lowest supported version of iOS in the PushSDK Framework and in the most recent releases of XCode.

Step 3.3: Add the Pushly Dependency to the Service Extension

In your <project_root>/ios/Podfile, add the NotificationServiceExtension at the same level as your main target:

Podfile

target 'NotificationServiceExtension' do
  pod 'Pushly', '>= 1.0', '< 2.0'
end

Example Podfile

require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'

platform :ios, min_ios_version_supported
prepare_react_native_project!

# If you are using a `react-native-flipper` your iOS build will fail when `NO_FLIPPER=1` is set.
# because `react-native-flipper` depends on (FlipperKit,...) that will be excluded
#
# To fix this you can also exclude `react-native-flipper` using a `react-native.config.js`
# ```js
# module.exports = {
#   dependencies: {
#     ...(process.env.NO_FLIPPER ? { 'react-native-flipper': { platforms: { ios: null } } } : {}),
# ```
flipper_config = ENV['NO_FLIPPER'] == "1" ? FlipperConfiguration.disabled : FlipperConfiguration.enabled

linkage = ENV['USE_FRAMEWORKS']
if linkage != nil
  Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
  use_frameworks! :linkage => linkage.to_sym
end

target 'PushlyDevApp' do
  config = use_native_modules!

  # Flags change depending on the env values.
  flags = get_default_flags()

  use_react_native!(
    :path => config[:reactNativePath],
    # Hermes is now enabled by default. Disable by setting this flag to false.
    # Upcoming versions of React Native may rely on get_default_flags(), but
    # we make it explicit here to aid in the React Native upgrade process.
    :hermes_enabled => flags[:hermes_enabled],
    :fabric_enabled => flags[:fabric_enabled],
    # Enables Flipper.
    #
    # Note that if you have use_frameworks! enabled, Flipper will not work and
    # you should disable the next line.
    # -- Disabling due to archive issues
    # :flipper_configuration => flipper_config,
    # An absolute path to your application root.
    :app_path => "#{Pod::Config.instance.installation_root}/.."
  )

  target 'PushlyDevAppTests' do
    inherit! :complete
    # Pods for testing
  end

  post_install do |installer|
    react_native_post_install(
      installer,
      # Set `mac_catalyst_enabled` to `true` in order to apply patches
      # necessary for Mac Catalyst builds
      :mac_catalyst_enabled => false
    )
    __apply_Xcode_12_5_M1_post_install_workaround(installer)
  end
end

target 'NotificationServiceExtension' do
  pod 'Pushly', '>= 1.0', '< 2.0'
end

Now that the service extension dependency has been added to the Podfile you will need to re-run installation. Within the <project_root>/ios directory, run: pod install.

Step 3.4: Update the Service Extension

Now, open the newly created Notification Service Extension and replace the code with the following:

Swift

import Pushly

class NotificationService: PNNotificationServiceExtension {
}

Objective-C

// Make sure to keep the header file import
#import "NotificationService.h"

@import Pushly;

@interface NotificationService ()

@property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;

@end

@implementation NotificationService

- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
    self.contentHandler = contentHandler;
    self.bestAttemptContent = [request.content mutableCopy];
    
    [PNNotificationServiceExtensionHandler didReceiveExtensionRequest:request content:self.bestAttemptContent withContentHandler:contentHandler];
}

- (void)serviceExtensionTimeWillExpire {
    // Called just before the extension will be terminated by the system.
    // Use this as an opportunity to deliver your "best attempt" at modified content, otherwise the original push payload will be used.
    [PNNotificationServiceExtensionHandler didRecieveExtensionTimeWillExpire:self.bestAttemptContent withContentHandler:self.contentHandler];

    self.contentHandler(self.bestAttemptContent);
}

@end

If Xcode warns that it cannot find Pushly, make sure you have a physical device or the "Any iOS Device" option selected as your build destination.

Step 3.4: Add Capabilities to Primary Application Target

The Push Notifications capability should only be added to the primary application target.

Select the root project and then your primary application target > Signing & Capabilities

Click the + Capability and add Push Notifications.

Click the + Capability and add Background Modes.

After adding the Background Modes capability ensure that Remote Notifications are enabled.

Click the + Capability and add App Groups.

Click the + symbol located inside the App Groups section to add a new named container. To ensure that the PushSDK can properly capture information the container should be named group.{app-bundle-id}.push.

Check the box next to the newly created App Group in the primary application target.

Step 3.5: Add Capabilities to The Notification Service Extension

Now in your NotificationServiceExtension target select the Signing & Capabilities tab.

Click the + Capability and add App Groups.

Finally, check the box next to the newly created App Group.

Step 4: SDK Initialization

In your index.tsx or app.tsx file initialize the PushSDK using the example implementation code below.

Replace the REPLACE_WITH_SDK_KEY in the setConfiguration method with the SDK Key from the platform settings page.

index.tsx

...
import { PushSDK, LogLevel } from '@pushly/push-sdk-react-native';

export const App = () => {
    ...

    // We recommend initializing the PushSDK in a useEffect block
    // to prevent the application from attempting to invoke
    // PushSDK.setConfiguration() on each rerender
    React.useEffect(() => {
        PushSDK.setLogLevel(LogLevel.INFO);
        PushSDK.setConfiguration({ appKey: 'REPLACE_WITH_SDK_KEY' });

        PushSDK.showNativeNotificationPermissionPrompt().then(({ granted }) => {
            console.log(`Permissions granted: ${granted}`);
        });
    }, []);
    
    // The rest of the your app
    ...
};

Run your application on either an Android device or emulator (ensure the emulator has Google Play Store Services installed) or on an iOS device, if building for iOS, to make sure it builds correctly.

The code you added in the previous step will show the push permission dialog upon app open. This can be customized by using SDK methods to control when the dialog shows.

After accepting the dialog log into the platform and navigate to Notifications > Create Notification and send your first notification, targeting the appropriate Native: iOS or Native: Android channel, to your device.

Next Steps

Once you have confirmed the SDK is working properly you may continue to add additional optional functionality like:

• Handling notification opens / app links / deep linking

• Attaching attributes to a subscriber's profile

• Sending information about what content a subscriber interacts with