facebookarchive/FBNotifications

Facebook In-App Notifications enables you to create rich and customizable in-app notifications and deliver them via push notifications, based on the actions people take in your app. You can use text, photos, animated GIFs, buttons or extend the open format to suit your needs.

Getting Started on iOS

To get started on iOS, install the framework using one of these options:

• CocoaPods

Add the following line to your Podfile:

pod 'FBNotifications'

Run pod install, and you should now have the latest framework installed.

• Carthage

Add the following line to your Cartfile:

github "facebook/FBNotifications"

Run carthage update, and you should now have the latest version of the framework in your Carthage folder.

After you've installed the framework, you would need to add the following to your application delegate to present the notification:

Using Objective-C:

/// Present In-App Notification from remote notification (if present).
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(nonnull void (^)(UIBackgroundFetchResult))completionHandler {
  FBNotificationsManager *notificationsManager = [FBNotificationsManager sharedManager];
  [notificationsManager presentPushCardForRemoteNotificationPayload:userInfo
                                                 fromViewController:nil
                                                         completion:^(FBNCardViewController * _Nullable viewController, NSError * _Nullable error) {
                                                           if (error) {
                                                             completionHandler(UIBackgroundFetchResultFailed);
                                                           } else {
                                                             completionHandler(UIBackgroundFetchResultNewData);
                                                           }
                                                         }];
}

Using Swift:

/// Present In-App Notification from remote notification (if present).
func application(application: UIApplication, didReceiveRemoteNotification userInfo: [NSObject : AnyObject], fetchCompletionHandler completionHandler: (UIBackgroundFetchResult) -> Void) {
  FBNotificationsManager.sharedManager().presentPushCardForRemoteNotificationPayload(userInfo, fromViewController: nil) { viewController, error in
    if let _ error = error {
      completionHandler(.Failed)
    } else {
      completionHandler(.NewData)
    }
  }
}

Getting Started on Android

To get started on Android, add the following to your gradle dependencies:

compile 'com.facebook.android:notifications:1.+'

After you've added the dependency, you'll have to set up an FCM listener service, and add the following to your service:

@Override
public void onMessageReceived(RemoteMessage remoteMessage) {
    Bundle data = new Bundle();
    for (Map.Entry<String, String> entry : remoteMessage.getData().entrySet()) {
      data.putString(entry.getKey(), entry.getValue());
    }
  
    NotificationsManager.presentNotification(
        this,
        data,
        new Intent(getApplicationContext(), MainActivity.class)
    );
}

Then when all the content for the notification is ready - it will automatically present the notification to the end user with a pending intent to present a card on open. To hand-off the necessary data from the intent - you need to handle the notification in the onCreate function of your Main Activity:

public class MainActivity extends AppCompatActivity {
  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    NotificationsManager.presentCardFromNotification(this);
  }
}

For more help on getting started, take a look at our Facebook Push Campaigns Documentation.

In-App Notifications Format

In-app notifications are powered by a custom format that has an open specification available in this repository. The format describes all the possible values and combinations of content that can be rendered by the framework.

We are open to accepting contributions to the format and the format is constantly evolving. Any version of the framework is compatible with any previous version of the format in the same major version scope.

For example:

• Framework 1.0.0 is compatible with format version 1.0
• Framework 1.0.0 is not compatible with format version 1.5
• Framework 1.5.0 is compatible with format version 1.5
• Framework 1.5.1 is compatible with format version 1.5
• Framework 2.0.0 is not compatible with format version 1.0, or 1.5

Contributing

We want to make contributing to this project as easy and transparent as possible. Please refer to the Contribution Guidelines.

License

See the LICENSE file for source code. See the LICENSE-specification file for In-App Notifications format specification.