Forem: OneSignal

How to Add In-App Messages to a Flutter App

Pato — Fri, 03 Jun 2022 20:21:15 +0000

In-app messages (IAM) can help increase user engagement among active users, nudging them towards desired actions with targeted messages and dynamic content. These messages can be automated and personalized based on custom segmentation and trigger criteria. This tutorial will cover how to integrate OneSignal IAM into a Flutter app for both Android and iOS. It will also show you how to use message triggers to automate and customize your messages.

Creating the Flutter Project

Open your terminal and run the following command to create a new Flutter project

flutter create flutter_onesignal_iamcd flutter_onesignal_iam

Now run the following command to add Onesignal SDK to the flutter project

flutter pub add onesignal_flutter

Setting up your OneSignal Account

This tutorial requires a OneSignal account. You can either log in to your existing OneSignal account or create a new account for free. Then, click +New App/Website to begin setting up your OneSignal account.

Android Setup

As Flutter apps can target both Android and iOS, both of these platforms need to be set up individually. Let’s proceed with setting up Android for now — iOS can be added later.

Name your app and select Google Android (FCM) and use the following guide to generate a Firebase Server Key.

After you've input your Firebase Server Key and Firebase Sender ID, click Save & Continue.

On the next screen, select _ Flutter _ as your target SDK.

On the next page, you'll see your App ID — copy it for future reference. Don't click Done just yet. The Flutter app needs to be run on your device first before you complete this step.

The App ID is used to initialize the OneSignal SDK. Add the following code to main.dart:

import 'package:flutter/material.dart';
import 'package:onesignal_flutter/onesignal_flutter.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({Key? key}) : super(key: key);

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  @override
  void initState() {
    super.initState();
    OneSignal.shared.setAppId("YOUR ONESIGNAL APP ID HERE");
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('OneSignal IAM'),
      ),
      body: const Center(child: Text('OneSignal IAM Example')),
    );
  }
}

Now, run the app on your device. Then, return to your OneSignal account and click on Check Subscribed Users. A message showing your device model will be shown.

iOS Setup

In your OneSignal account, navigate _ Settings _ and click on Apple iOS (APNs). In this step, you will be asked for an iOS push certificate and its password.

Check out the linked documentation to learn how to generate an iOS push certificate. The easiest method is to useOneSignal provisionator, which directly generates the p12 file and password without much hassle. Once generated, upload the p12 file and password, and continue to the next screen.

Upload Your APNs Cert

The certificate password is the one used to encrypt the exported certificate. If you left the password empty, do not enter a value for Certificate Password. OneSignal will verify the certificate can be used for push notifications upon clicking the continue button.

Select Flutter SDK on this screen, the next screen is identical to the Android configuration screen. Running the same code for iOS will work without any further modifications.

At the bottom of the Apple iOS (APNs) Configuration screen, a warning will appear saying that your user has not subscribed. This is because we have not yet asked for permission to send push notification. We will be asking for opt-in permission using in app messages later in this article.

Sending an In-App Message

Click on _ Message _ from the main navigation bar and then select _ In-App _ from the submenu that appears.

Onesignal provides default in-app messaging templates which can then be customized according to your use case and preference. From the list of templates, click on [Default Template] Welcome Message.

In the top right corner of the screen, select Actions — a drop-down menu will appear. If you'd like to edit and customize the default welcome message, click Edit to alter the template. If you've finished editing or would simply like to test the default message as is, click _ Resume _ from the drop-down menu. Then, run the app on your device.

In-App Messaging Triggers

You can use Triggers to choose when to show the in-app message to the user. There are some predefined Triggers such as "app open," as well as custom triggers that can be set programmatically using the addTrigger() function. To begin, let's try using a predefined trigger for showing an app rating message.

If you're using a free OneSignal plan, you will only be able to have one in-app message live at a time. Before creating the new message, you'll need to pause the welcome in-app message by clicking _ Actions _ and then _ Pause _ from the drop-down menu. Then, navigate back to the main in-app messages screen and select [Default Template] App Store Rating. Select _ Actions _ > Edit and then scroll down on the editing screen to the section entitled 3. Triggers.

When should users see this message? select _ When certain conditions are satisfied during the session . You should see two form fields for **_session duration** and _ duration since the last in-app . Enter a session duration greater than 10 seconds for demonstration purposes, then scroll down to the bottom of the page and click on the blue **_Update Message** button.

Then, from the list of In-app messages, click _ Actions _ > _ Resume _ for this message and then open the app. After 10 seconds, you should see a rating request message inside your app.

This example demonstrates the power of in-app messaging! Using OneSignal's in-app messaging tool, you can:

Add and remove in-app messages remotely without requiring any app update.
Leverage useful, pre-made triggers such as _ app open , **_session duration** , and _ duration since the last in-app message _, along with the option to club these triggers with an OR operation. This makes implementing a wide range of in-app messaging strategies possible without requiring any code customizations!

Asking for Push Permission (iOS)

In iOS, a user needs to grant permission to an app in order to receive push notifications. As a general rule of thumb, you don’t want to ask a user for push notification permission immediately when they first launch the app because they aren't likely to understand the value of notifications at that early stage of adoption. Onesignal provides a predefined in-app messaging template to help you time your opt-in request and give users more context to inform their opt-in decision.

To try out this prompt, pause the current message (if you're using a free account), then click Action > _ Resume _ to enable the [Default Template] Push Permission Prompt. This prompt has been set to show the user a message asking for permission upon launching the app, but the trigger and message content can be customized to provide a better user experience and increase the likelihood of opt-in.

If the clicks to Allow notifications in the in-app message, it will automatically trigger the native iOS permission prompt. If they click Maybe Later , they will be opted out of notifications but can be prompted again later with an in-app message encouraging them to revisit this decision.

If a user denies permission to receive notifications the first time around, but later clicks _ Allow _ when they are re-prompted, they will be taken to the notification settings where they will have to manually allow the app to show notifications — this is a restriction imposed by iOS.

Using Custom Triggers in In-App Messaging

Custom triggers are key-value pairs of string or integer types to which the SDK responds. Whenever the condition set is satisfied, the trigger is initiated. Custom triggers can be clubbed together with AND and OR to create more complex triggers.

For demonstration purposes, let’s build a button that, when tapped eight times, will trigger a promotional in-app message.

To do so, open main.dart and add a floating action button to the scaffold, along with a variable to save the button tap count.

void main() {
 runApp(const MyApp());
}

class MyApp extends StatelessWidget {
 const MyApp({Key? key}) : super(key: key);

 // This widget is the root of your application.
 @override
 Widget build(BuildContext context) {
   return const MaterialApp(
     home: MyHomePage(),
   );
 }
}

class MyHomePage extends StatefulWidget {
 const MyHomePage({Key? key}) : super(key: key);

 @override
 State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
 int taps = 0;

 @override
 void initState() {
   super.initState();
   initMessaging();
 }

 Future<void> initMessaging() async {
   await OneSignal.shared.setAppId("f3afbef4-2fe4-452b-a391-b8175c2b65a1");
 }

 @override
 Widget build(BuildContext context) {
   return Scaffold(
     appBar: AppBar(
       title: const Text('OneSignal IAM'),
     ),
     floatingActionButton: FloatingActionButton(
       onPressed: () {
         setState(() {
           taps = taps + 1;
         });
         OneSignal.shared.addTrigger('taps', taps);
       },
       child: const Icon(Icons.add),
     ),
     body: const Center(child: Text('IAM')),
   );
 }

Open the OneSignal dashboard, select the [Default Template] 10% Off Promotional template, and click _ Actions _ > _ Edit . On the editing page, scroll down until you see the **_3. Triggers** section. Under the question, When should users see this message? select When certain conditions are satisfied during the session. Click IN-APP TRIGGER and input taps is 8 to the appropriate form fields, as shown below.

Finally, click _ Add Trigger _ and then scroll to the bottom of the page and click Update Message. If you followed along and implemented the previous example, the push permission prompt will still be live. If you are using a free plan, pause that message, navigate back to your promotional message, and click Actions > Resume to set this one live. Now, run the app with the updated code. Tap the button 8 times and the promotional message should pop up on your screen.

This custom trigger was an example of key is value pair. There are other conditions on which the triggers can be set as well.

One of the best things about Onesignal's in-app messaging tool is the ability to overhaul the design of the popup without doing an app update. To demonstrate, let's update the current 10% promotional message to something more appropriate. To do so, first click _ Actions _ > Pause to pause the current message, then click on _ Edit _.

All the UI elements are highly customizable in the OneSignal message builder, as can be seen in the video below. Almost all aspects of text can be formatted to suit the design language of your app.

Messages also do not have to be fixed to a particular type of layout. All the UI elements can be reordered on the fly without requiring an app update.

In-app messages also support GIFs!

Let’s apply all these changes, scroll to the bottom and click _ Update Message _. No need to update any code, just open the app again!

Adding Click Actions in Messages

Onesignal provides a handful of click actions out of the box that can be customized from the dashboard. There is also a Custom Action ID, in which a custom action ID string is sent, which can handle custom cases such as deep-linking, app updates, or any other functionality.

Let’s implement a URL click action first. Implementing an URL means that when a user clicks on the button, they will be taken to the specified URL. To add a link, click Actions > _ Edit _ on the promotional message (if you closed out from the last example) and scroll down to the _ Button 1 _ box and update the URL. Then, scroll down to the bottom of the page and click _ Update Message . Then, click _ Action _ > **_Resume** to resume the message. To test it out, open your app and tap the button 8 times again.

Once the message pops up, press the first button and you should be taken to the website link you provided.

Custom Click Action ( Custom Action ID)

Creating custom click actions requires developer support. All the use cases that may be necessary for the future should be listed beforehand and handled in the code.

In this example let’s try deep linking to a second page when pressing the button. To do so, create a new file called success_screen.dart and add this code.

import 'package:flutter/material.dart';
class SuccessScreen extends StatelessWidget {
  const SuccessScreen({Key? key}) : super(key: key);
  @override
  Widget build(BuildContext context) {
    return const Scaffold(
      body: Center(
        child: Text(
          'Success',
          style: TextStyle(fontWeight: FontWeight.bold, fontSize: 42),
        ),
      ),
    );
  }

Now, go to the initMessaging() in main.dart and add a setInAppMessageClickedHandler to listen to any click actions that happen on the message.

 Future<void> initMessaging() async {
    await OneSignal.shared.setAppId("f3afbef4-2fe4-452b-a391-b8175c2b65a1");
    OneSignal.shared.setInAppMessageClickedHandler((action) {
      if (action.clickName == 'successPage') {
        Navigator.of(context)
            .push(MaterialPageRoute(builder: (_) => const SuccessScreen()));
      }
    });
  }

This works as follows:

set InAppMessageClickedHandler listens to any action event that is emitted by interacting with any UI element.
When a click action is set in the OneSignal console, it means that an action binds to that UI element.
Whenever an interaction occurs with that element, the action is triggered.
If that action is a pre-defined one, such as opening a URL, then while the click handler will listen to the action being emitted, the action to perform is already handled by the SDK and will result in opening the URL in the browser.
For action IDs that you specify, you can build different use cases as shown in the above example to handle different action IDs.
In the above snippet, the action has many properties which can be further leveraged to create better user experiences.

Now, click Action > Pause to pause the current message and then select Edit. Scroll down to the button to which a click action has to be added. Then, select Custom Action ID and give the action a name such as successPage.

Next, scroll down to the bottom of the screen and click Update Message and Resume the message via the Actions menu. Now, run the updated app.

When you click on the button, you should have successfully implemented deep linking!

Share Your Feedback

We'd love to know what you think and answer any additional questions you have. To connect with us, create an issue on GitHub or ping us on the OneSignalDevs Discord server to share your experience. We appreciate any insight you can share to help us better serve Vue.js users!

To stay in the loop with the latest product updates and innovations, follow the OneSignal Developers Twitter. For additional support and dev inspiration, tap into our global developer community.

>> Connect with the OneSignal Developer Community

This guest post was authored by Chinmay Kabi

Fixing Memory Leaks in Rust

onesignaldevs — Mon, 23 May 2022 23:35:29 +0000

At OneSignal, we love Rust. We have blogged before about pivoting some of our core business systems to Rust, how the language has changed over the past several years, and interesting things we’ve learned about the thread safety model. Other than Onepush, the core of our push notification delivery system, we also use Rust for a gRPC service and multiple Kafka consumers. In this article, we’re going to talk about a stumbling block that we ran into with one of our newest Rust projects.

The Challenge

Near the end of February, we announced the general availability of our Journeys feature. Journeys allows customers to easily build complex messaging workflows with a no-code UI. It is powered by a few gRPC services and a Kafka consumer written in Rust, called JourneyX. Journeys is an event-driven system, so everything that happens within a journey workflow is triggered by an event on a Kafka stream. These events are consumed by JourneyX (journey executor).

A few weeks ago, as Journeys adoption started to increase and JourneyX started to process more events, we began to notice a disturbing pattern in its memory usage. The most active processes were consistently utilizing lots of memory, then getting killed by the kernel. The Linux kernel has a piece of functionality called the OOM (out-of-memory) killer, which will automatically kill processes when they consume too much of the system memory. This prevents the system from becoming unstable or locking up due to resource starvation. In our case, the JourneyX processes were constantly being killed, restarted, and killed again by the OOM killer. This showed up on a graph as a sawtooth pattern of rapid allocation and near-instant deallocation when the process was killed. Memory usage would spike up to 17 GiB in the busiest processes, but we expect one of these worker processes to need under 1 GiB.

Graph of memory usage for a single JourneyX process over 24 hours

This caused a few issues for us. Obviously from a theoretical perspective, we didn’t want a system that was constantly being killed by the OS. The operations it performed were idempotent, so we weren’t necessarily worried about sending multiple notifications due to this problem. The issue did create alert spam for us, which led us to over-provision on memory. The constant crashing also caused concern about the long-term health of the service.

BUT WAIT! I hear you say — doesn’t Rust’s borrow checker prevent memory errors? Isn’t Rust supposed to be “safe?” It turns out that, according to Rust’s rules, leaking memory is completely safe! In fact, we can purposely leak as much memory as we want using the function std::mem::forget. The only thing “unsafe” about memory leaks is that they might eventually result in your program being killed by the kernel (as JourneyX does in this case). A program ending in a predictable way is also considered safe behavior. Rust’s safety guarantees exist to protect us from invalid memory access, not resource starvation.

Troubleshooting with Distributed Tracing

In addition to Rust, we’re big fans of distributed tracing. If you’re not familiar with tracing concepts, check out this document from Honeycomb's Introduction to Distributed Tracing. All of our services report trace data and send W3C trace propagation headers to one another so that we can tie operations together through our system. Tracing data in Honeycomb is now our first stop when our on-call team gets paged. Here is an example trace from our Journeys processing system.

In some languages, tracing instrumentation can be accomplished largely through automated means. In our Ruby on Rails codebase, the Honeycomb and OpenTelemetry libraries use ActiveSupport hooks to add trace spans around operations like HTTP handlers and ActiveRecord queries. Rust is a lot of things, but it's not really “runtime configurable.” There are libraries that allow you to write Rust code that can be configured at runtime, but most Rust code is not written in this way. Because of this, we need to add a lot of manual instrumentation to our Rust apps. We need to manually delineate operations into spans and add fields on those spans.

We have a few choices for adding these data to our codebases. We could use the Rust opentelemetry library, which is generic and standardized according to the OpenTelemetry specification. Instead, we use the tracing library, which is a façade crate, similar to log. It allows us to connect and configure multiple tracing backends, and it captures data from the log crate straight out of the box.

If we had some Rust code like this:

fn http_handler() {
    let data = get_data();
    let result = perform_expensive_computation(data);
}

And you wanted to put a span around the perform_expensive_computation function, you could do so like this:

use tracing::info_span;

fn http_handler() {
    let data = get_data();
    let span = info_span!(?data, "perform_expensive_computation");
    let _guard = span.enter();
    let result = perform_expensive_computation(data);
}

The enter function returns a guard that marks the time in which the span is active. It begins when you first call enter, and ends when the guard value is dropped as it goes out of scope. Rust’s Drop trait allows it to easily provide the functionality to run at the time it’s deallocated.

Within JourneyX, surrounding the “send a notification” HTTP request, we had the following snippet:

let (res, body) = {
    let query_span = tracing::info_span!("send HTTP request");
    let _guard = query_span.enter();
    self.client.request(body).await?.into_parts()
};

Now experienced users of the tracing library may already know the issue, but to those of us who aren’t intimately familiar with the API, this looks quite reasonable based on what I’ve already told you. If we look at the documentation for the enter method though, we may notice something that calls this into question.

Warning : in asynchronous code that uses async/await syntax, Span::enter should be used very carefully or avoided entirely. Holding the drop guard returned by Span::enter across .await points will result in incorrect traces.

Notice the last line of the block above uses .await when calling the request method. This is going to cause a problem for us. To see why, we need to look at the conceptual models for tracing and async Rust.

The .enter method from tracing returns what is conventionally referred to as a “guard” type. One of the great benefits of Rust’s ownership and lifetime system is that it provides the ability to write destructors for any type and to be sure about when those destructors are going to run. We can do this by implementing the Drop trait for any type. The interface looks (very, very roughly) like this:

struct EnterGuard {
}

impl Span {
  fn enter(&self) -> EnterGuard {
    begin_span(self.id);
    EnterGuard { id: self.id }
  }
}

impl Drop for EnterSpan {
  fn drop(&mut self) {
    end_span();
  }
}

Because of Rust’s destructor rules, the EnterSpan type will call the end_span function whenever the variable it’s attached to goes out of scope. Here is an annotated example:

fn do_something() -> i32 {
  let x = {
    let span = Span::new();
    let _guard = span.enter(); // begin_span called
    do_expensive_computation()
  }; // end_span called by the Drop of `_guard`

  let span = Span::new();
  let _guard = span.enter(); // begin_span called
  more_compute(x)
} // end_span called by the Drop of `_guard`

This is great because it means that most of the time, we just don’t need to worry about remembering to mark a span as complete. It just works (tm). For synchronous code, that’s definitely the case, but it falls apart for async code. To see why that's the case, let’s look at the pseudocode for begin_span and end_span.

thread_local! {
  static ACTIVE_SPANS: RefCell<Vec<SpanId>> = RefCell::new(Vec::new());
}

fn begin_span(id: SpanId) {
  ACTIVE_SPANS.with(|s| s.borrow_mut().push(id));
}

fn end_span() {
  ACTIVE_SPANS.with(|s| s.borrow_mut().pop());
}

Now this is incredibly simplified (please don’t get mad at me, tracing maintainers) but the general idea is that each thread maintains a stack of span IDs that represents the hierarchy of spans currently active. This works great for synchronous code, when each OS thread can maintain this state independently. When we use async code, however, we have multiple tasks running concurrently on top of the same OS thread, sharing thread locals. And the Drop handler for our EnterGuard won’t be called when context switches happen. That means if we were to write code like this:

let mut tasks = futures::stream::FuturesUnordered::new();
for id in 0..5 {
  tasks.push(async move {
    let span = info_span!(id, "task");
    let _guard = span.enter();
    tokio::time::sleep(std::time::Duration::from_millis(100)).await;
  });
}
futures::future::join_all(tasks).await;

Let’s consider what happens to our thread-local stack at each stage in the task execution. For simplicity's sake, we’ll assume for now that these five tasks are executed in the order that they were enqueued, although this typically isn't the case.

Notice that at both the beginning and end of the spans there are large discrepancies in the state of the stack. When spans are beginning, we create a hierarchy on the stack that indicates all of the tasks have a parent/child relationship with one another, but this is not accurate. When spans end, we pop the wrong task span off of the stack, because the state of the stack is inconsistent with reality.

In our production code, this issue caused memory usage to skyrocket, because our span tree was essentially expanding endlessly and never able to shrink. Because of how quickly concurrent operations were occurring, the stack was continuously having new spans added to it, and previous spans (now with tens of thousands of children) would never be dropped.

The Solution

So what’s the fix? It’s very simple. Recall that the original code looked like this:

let (res, body) = {
    let query_span = tracing::info_span!("send HTTP request");
    let _guard = query_span.enter();
    self.client.request(body).await?.into_parts()
};

We need to update it to this:

let (res, body) = {
    let query_span = tracing::info_span!("send HTTP request");
    self.client.request(body).instrument(query_span).await?.into_parts()
};

It’s a subtle change, but absolutely critical. Let’s see how this works. This is once again simplified for the sake of brevity.

pub trait Instrument {
  fn instrument(self, span: Span) -> Instrumented<Self> {
    Instrumented { span, inner: self }
  }
}

pub struct Instrumented<T> {
  span: Span,
  inner: T,
}

impl<T> Future for Instrumented<T> where T: Future {
  type Output = T::Output;

  fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
      let _enter = self.span.enter();
      self.inner.poll(cx)
  }
}

There are a few things going on here. First off, we have the Instrument trait. This is an extension trait that exists only to allow us to build an Instrumented struct from an arbitrary Future. Instrumented is a wrapper future that allows us to have tight control over the polling logic. In this case, we use .enter to begin the span while the underlying future is polled, and end the span when the context switches.

This works because poll is the context-switching boundary of a future. While poll is being called, this future and its children are the only things burning CPU time on the thread. Other futures may be sleeping in the background, but nothing else can preempt the currently running future’s poll.

Tracing’s .enter method isn’t the only instance of this. There are many types that were not designed to be held across await points. Mutex, RwLock, and RefCell for example all have guard types that hold a lock on a resource and could result in deadlocks if held across await points.

So where do we go from here? There’s a subtle code difference that results in both incorrect observability results and potentially extreme memory usage. Normally, issues like this could be caught by the Rust compiler. There is an RFC to add a lint to the compiler called must_not_suspend which will allow developers to mark types as being unsafe to hold across await points. But there is still a lot of work remaining before this will land, so what should we do in the meantime?

Rust’s standard linting tool, Clippy, has existing lints for the Mutex and RefCell types, but we don’t want to have to create a custom Clippy lint for every type like this. A few weeks ago, I submitted rust-lang/clippy#8707 which allows Clippy users to provide a list of types that are not allowed to be held across await points. Once this makes it to Clippy’s stable release branch, users will be able to add the following to their clippy.toml files:

await-holding-invalid-types = [
  "tracing::trace::Entered",
  "tracing::trace::EnteredSpan",
]

This will provide users with a warning if a span’s enter guard is held across an await point when they run cargo Clippy. The warnings will look like this:

error: `tracing::trace::Entered` may not be held across an `await` point per `clippy.toml`
  --> main.rs:10:9
   |
LL | let _guard = span.enter();
   | ^^^^^^

This provides some amount of safeguarding, though the must_not_suspend lint will be a welcome improvement, as it will not require an explicit configuration in order to work.

Thank you for coming with me on this journey of memory leak discovery! I’ll leave you with a four-day graph of the memory usage of our JourneyX processes. It’s quite clear when this change was deployed that we instantly fixed the issue with this very subtle code change.

A graph of the memory usage of our JourneyX processes over four days.

If you’re interested in working on using Rust in production to create high-throughput evented systems, distributed systems, or any other areas of engineering, please check out the OneSignal careers page!

>> Browse OneSignal Careers

How to Add In-App Messages in React Native (Expo)

Pato — Fri, 20 May 2022 21:07:27 +0000

In-app messages (IAM) are highly customizable pop-up interstitials that mobile app user receive inside your application. Unlike push notifications, IAM don’t require opt-in permission and they only show when the users are actively using your application.

OneSignal & Your Browser's Push API

It’s no secret that in-app messages can help you engage and retain app users. This tutorial will show you how to integrate with the React Native OneSignal NPM package to leverage IAM in your React app.

Some valuable use cases for IAM include:

User Onboarding: Guide your users through getting started with your application. Use an in-app slide carousel to build an effective onboarding process, introduce them to key application features, and emphasize the value your app will provide.
Announcing New Products & Features: Inform your users when you have added new products and features to the application to improve adoption and enhance the UX.
Requesting Push Permission & Location Access: Provide users with more context to inform their opt-in decision or request location or other access permissions that are vital to your application.
Encouraging Referrals: Allow your users to invite their friends to your application with a single click to grow your active users and build community.

This tutorial will cover how to integrate the React Native Expo OneSignal Plugin (managed workflow) into your app in order to gain in-app messaging functionality. Part one of this guide covers the OneSignal setup process. Part two of this guide covers how to integrate OneSignal with React using our NPM package.

Guide Overview

Part 1: Set up Your OneSignal Account (for free!)
Part 2: Push Notification Setup in React
Send an In-App Message to Your Android Device

This tutorial requires some basic knowledge of React Native (Expo). I'm using the Expo CLI to generate my project and NodeJS version 14.16.

Additional React Setup Resources:

React Native (Expo) plugin Sample Ap

Part 1: Set Up Your OneSignal Account

To begin, login to your OneSignal account or create a free account. Then, click on the blue button entitled _ New App/Website _ to configure your OneSignal account to fit your app or website.

Insert the name of your app or website. Select _ Google Android _ as your platform.

Click on the blue button entitled, _ Next: Configure Your Platform _.

Google Android FCM Configuration

It’s time to configure your Android app using a Firebase Server key. All Android apps require this key and the server ID if you want to send push notifications. If you don’t have the Firebase Server Keys, take a look at our documentation to learn how to generate a Firebase server API key.

Now select your target SDK. We'll take you through the steps to get your first user and send your first test notification.

On the next screen that appears, you will see your app ID — copy that app ID because you will use it inside of your Expo Application. DO NOT click to Check Subscribed Users or Done yet.

Part 2: Push Notification Setup In React Native Expo

Creating Your React App

Inside of your terminal, run the following commands to create a new React project using Create

Expo App:

expo init onesignal-rn-expo

When asked, selec any of the options under the Managed Workflow. In my case, I selected the first option, which is blank.

cd onesignal-rn-expo
expo start

For the official Expo, documentation click here.

Install OneSignal Expo Plugin

Inside of your project folder, open your terminal and run the following command to install the OneSignal Expo Plugin package.

expo install onesignal-expo-plugin

Next, install the React Native OneSignal plugin by running the following command:

yarn add react-native-onesignal

Even though onesignal-expo-plugin defines react-native-onesignal as a dependency and it gets put into the node_module, it will make sure the native parts get built.

If you forgot to run the following command after you have built your project, you can fix this by running expo prebuild --clean. This should delete android and ios and do a clean native build, then run the yarn add react-native-onesignal.

Configuration in app.json / app.config.js

Inside the app.json/app.config.js file, add the plugin to the plugin array:

App.json

{
  "plugins": [
    [
      "onesignal-expo-plugin",
      {
        "mode": "development",
        "devTeam": "91SW8A37CR"
      }
    ]
  ]
}

App.config.js

export default {
...
plugins: [
        [
        "onesignal-expo-plugin",
            {
                mode: process.env.NODE_ENV || "development",
                devTeam: "91SW8A37CR"
            }
        ]
    ]
};

Plugin Options

mode: used to configure APNs environment entitlement.
"development"
"production"
devTeam: *optional* used to configure Apple Team ID. You can find your Apple Team ID by running expo credentials:manager.

Example:

{
    "extra": {
        "oneSignalAppId": "<YOUR APP ID HERE>"
    }
}

You can then access the value to pass to the setAppId function:

import OneSignal from 'react-native-onesignal';
import Constants from "expo-constants";
OneSignal.setAppId(Constants.manifest.extra.oneSignalAppId);

Alternatively, pass the OneSignal app ID directly to the function:

import OneSignal from 'react-native-onesignal';
import Constants from "expo-constants";

OneSignal.setAppId("YOUR-ONESIGNAL-APP-ID");

Run & Build your Application

expo prebuild
# Build your native iOS project
$ expo run:ios
# Build your native Android project
expo run:android

Send an In-App Message to your Android Device

I recommend you run the application on an actual Android device to test the in-app messages. To do so, you will need to connect your Android device and enable developer mode.

Once you have connected to the device and enabled developer mode, run the application on your device by selecting your device as the target device. In my example, I’m running the app on a Google Pixel 5.

Once you have opened the application on your device, the device will be automatically be subscribed to notifications. Now, your device will be able to receive notifications sent by OneSignal.

To complete the setup process, return to your OneSignal dashboard to the point at which you previously left off. Click on the _ Check Subscribed Users _ button and a green message will appear like the one in the image below.

Click on the _ Done _ button.

Create an In-App Message

It’s time to send your first in-app message! To do so, login to your OneSignal account and navigate to the Dashboard tab. On the dashboard page, click on the tab that says Messages and you will be redirected to a new page.

Select the _ In-App _ tab from the submenu.

After clicking on _In-App, _ you will see the In-App Messages dashboard (pictured below). Click on the blue button New In-App button to create your first message.

On this page, you customize the In-App Message, from the content to display, the position, the image, your audience, and more.

Once you have finishing configuring sections one and two, scroll down to the triggers section (Section three. For testing purposes, select the _ On app open _ option. This option will automatically trigger the in-app message to appear when the app is opened.

Lastly, in the Schedule section, make sure your configuration looks like the following:

Under Schedule, select "Immediately," "Show forever," "Show until dismissed," and "Only once."

This configuration will send the message immediately and only once when you open the app.

Now it's time to set your in-app message live! To do so, click on the blue button that says _ Make Message Live _.

Connect With Us

Don’t forget to follow the OneSignal Developers Twitter and join our Discord server to learn more and connect with the OneSignal community of developers around the world.

Want to learn more about the OneSignal community? Visit our official website.

How to Send Push Notifications with the OneSignal NodeJS Client SDK

Pato — Fri, 13 May 2022 16:25:56 +0000

It’s no secret that push notifications can help you engage and retain app users. In this tutorial, we'll show you how to use the OneSignal NodeJS Client SDK to interact with all the OneSignal functionalities that you have available in our REST API but we made it easier for you with this wrapper.

Using the OneSignal NodeJS Client SDK is very useful because it can help you integrate OneSignal into different workflows that your applications may have.

Useful resources:

OneSignal & Your Browser's Push API

The Push API gives applications the ability to receive messages from a server whether or not the app is in the foreground or currently loaded on a user agent. This lets you deliver asynchronous notifications and updates to users who opt-in, resulting in better engagement with timely new content.

This tutorial will cover an overview the usage of our API with the OneSignal NodeJS Client SDK.

Guide Overview

Part 1: OneSignal REST API Overview
Part 2: Push Notification In NodeJS

This tutorial requires some basic knowledge of NodeJS and usage of REST APIs. I'm using the OneSignal Account along with:

App with OneSignal integrated (mobile, web, or game)
NPM (I’m using NPM version v6.14.11)
NodeJS (I’m using NodeJS v16.14.2)

Part 1: OneSignal REST API Overview

Sending Notifications

The OneSignal Push API allows you to programmatically send push notifications. The push notifications can be sent to different segments (by default you send them to all subscribed users) and even specific devices using the User ID. Another cool feature of the OneSignal REST API is the ability to cancel notifications that have been scheduled.

View Notification

One of my favorite endpoints to use with the OneSignal REST API is the view notification endpoint. This endpoint allows you to gather information about the notifications and outcomes associated with them. For example, the returned data can tell you see the number of notifications that have not been sent out, the number of notifications that got delivered, the number of confirmed deliveries, and much more information. If you want to learn more about all the data returned by this endpoint visit our rest API reference .

Our API can do way more than just send a notification and view data from that notification. If you want to learn more about our whole REST API, visit the OneSignal REST API overview page.

The cool thing about the NodeJS client library is that you don’t have to worry about the whole REST API setup in your NodeJS project, we handle all the boilerplate so you don’t have to worry about it ;)

Creating Your NodeJS App

Inside of your terminal run the following commands to create a new NodeJS project using NPM:

npm init

After entering the previous npm command, answer all the questions that will appear on your terminal. These questions will generate the values of your package.json.

Your package.json file will look similar to this:

{
    "name": "myapp",
    "version": "1.0.0",
    "description": "",
    "main": "index.js",
    “type”: “module”
    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1"
    },
    "author": "",
    "license": "ISC"
}

Make sure you add the type property.

Part 2: Push Notifications In NodeJS

Setup your NodeJS App

The first thing you need to do is to create an index.js file. This file will contain all code necessary to send and view your notifications.

At the top of this file, add the request npm package. This package will help us make API calls to the OneSignal endpoints in an easier way than doing it with NodeJS natively.

import * as OneSignal from '@onesignal/node-onesignal';

Now, run npm install @onesignal/node-onesignal --save to add the OneSignal NodeJS SDK Client NPM package to your project. After you have installed the OneSignal NPM package, add the following variable to your index.js after the OneSignal import.

const ONE_SIGNAL_APP_ID = 'ONESIGNAL_APP_ID';

How to get the API KEY and the APP ID from OneSignal? Navigate to the OneSignal Dashboard, and navigate to the app you created inside of OneSignal. Once you have selected the app you want to work with during this how-to guide, the dashboard page will open up.

Navigate to the settings page, by clicking the S _ ettings _ tab.

Inside of settings, click on Keys & IDs. On this page, you will see your OneSignal App ID and your API key.

Now that you are in the Settings > Keys & IDs tab, you can copy the OneSignal App ID and the REST API KEY.

Note: Another quick way to access the OneSignal App ID is by copying it from the URL.

Keep in mind that if you want to create an app using the OneSignal NodeJS Client, you will need the User Authentication Key.

Token Builder

To authentificate the app, you will need to use your OneSignal REST API key. Create a key provider object with the function getToken() that returns your key.

Returns: Your key. In the background when you use this variable app_key_provider.getToken() gets executed.

const app_key_provider = {
    getToken() {
        return 'ONESIGNAL_REST_API_KEY';
    }
};

Client Configuration

We can configure the client using the createConfiguration() function. The configuration object can be used to set the app_key_provider properties.

const configuration = OneSignal.createConfiguration({
    authMethods: {
        user_key: {
            tokenProvider: user_key_provider
        },
        app_key: {
            tokenProvider: app_key_provider
        }
    }
});
const client = new OneSignal.DefaultApi(configuration);

Create Notification

Create a push notification and send it to the users of your app.

To send a push notification, you will add the following function that will make a call to the OneSignal REST API. This function takes a body parameter that represents the information that the push notification will contain.

const notification = new OneSignal.Notification();
notification.app_id = ONESIGNAL_APP_ID;
notification.included_segments = ['Subscribed Users'];
notification.contents = {
    en: "Hello OneSignal!"
};
const {id} = await client.createNotification(notification);

Notice we use object destructuring to store the ID of the notification in a variable called ID.

View a Notification

After you have sent a notification, view the notification information and outcomes associated with it using the notification id.

As you can see, I’m passing as the second parameter the id variable that contains the notification id after I have created the notification using the createNotification() method.

const response = await client.getNotification(ONESIGNAL_APP_ID, id);

Run Your Code

Thanks to our package.json, you will be able to run your nodejs code by opening your terminal and typing npm run start. After running this command you should see a notification appearing on your device if and only if you subscribed to notifications from your website, game, or app that you created and registered it in the OneSignal Dashboard.

Feel free to test other methods of the NodeJS Client SDK and let us know what you think!

Want to learn more about the OneSignal products and other technologies? Join our OneSignal Developers Community!

Join the OneSignal Developers Community

The OneSignal Developer community is a group of passionate individuals who work with OneSignal products. Community members have the opportunity to expand their network and knowledge across different technologies.

Connect on Twitter

Follow our OneSignal Developers Twitter to learn more about OneSignal, technical tips, and the latest events from OneSignal developers.

Join Our Discord Server

The OneSignal Developer community gathers on our public chat server, available on Discord. Our Discord server is a safe environment to network with other members, ask questions, and learn from each other. It is also a place to engage with the OneSignal product development team.

GraphQL and Push Notifications with OneSignal and TakeShape

Pato — Mon, 25 Apr 2022 16:05:38 +0000

By Jaden Baptista from TakeShape & Patricio Vargas from OneSignal

We're excited to share a sample project we’ve been working on with TakeShape which leverages our push notification solution with TakeShape’s powerful API mesh. This article explains what we accomplished and the steps we took to get there. If you want to follow along, you can check out the GitHub repo.

Project Goals

Build an app that will look up a country based on its abbreviation and send the user a push notification
Use OneSignal's SDK to do the subscription registration for push notifications
Send the actual notification with OneSignal using an API call from TakeShape
Use TakeShape to set up a pipeline for the data that can be triggered with a single GraphQL API call instead of multiple separate callsIt'll be our app → TakeShape API mesh → Countries API → TakeShape API mesh → OneSignal API → return to our app. All in one request.
Turn this into a starter project to help people get going with TakeShape and OneSignal
Try to make it look pretty so that people don't ridicule us for making something cool without it looking the part

Our Process

This tutorial will cover how to integrate OneSignal push notifications into your app using our typical setup process and how to send push notifications using the OneSignal REST API.

Part 1: Set Up Your OneSignal Account

To begin, login to your OneSignal account or create a free account. Then, click on the blue button entitled _ New App/Website _ to configure your OneSignal account to create your app or website.

Configure the name of your app or website. Select _ Web Push _ as your platform.

Click on the blue button entitled, _ Next: Configure Your Platform _.

Web Configuration

Under Choose Integration, select the _ Typical Site _ option.

In the Site Setup section, enter your chosen web configuration. In my case, the configuration looks like this:

Notice for testing purposes we entered our localhost URL (http://localhost:3000). If you are doing the same, make sure you click on the _ LOCAL TESTING _ option. This will ensure to treat HTTP localhost as HTTPS for testing.

Under _ Permission Prompt Setup _, you will see three vertical blue dots under the _ Actions _ header on the far right side of the screen. Click on the blue dots and select _ Edit _ from the drop-down menu.

A window will open with the configuration of our push notification Slide Prompt. Confirm that Auto-prompt is enabled (toggled to the right).

Under _ Show When _, you can choose how long your slide prompt will delay after a user visits your page. You can leave it as it is, or you can reduce the seconds so that your prompt appears sooner. Once you've chosen your delay time, click the grey _ Done _ button located at the bottom right corner of the window.

After clicking _ Done _, scroll down to the bottom of the page and click Save to save your auto-prompt configurations.

You will be redirected to a different page with an important step: Downloading the SDK files. Click _ DOWNLOAD ONESIGNAL SDK FILES _ and save them on your computer to retrieve later. We'll show you where to put them in a bit after we set up our site's directory.

Under the section entitled _ Add Code to Site _, you will see a grey button that allows you to copy the code snippet. Click the grey _ COPY CODE _ button.

Part 2: Create a New TakeShape Project

To set up that pipeline we mentioned earlier, we needed to find the right API. For this project, we were thinking of using something more fun and quirky like the PokeAPI, but we ended up settling on something a little more useful (well, I suppose that depends on how you spend your free time) with the CountriesAPI designed by Trevor Blades at Apollo. We’ve outlined our steps below so you can follow along.

To get started, go to takeshape.io and started a new project like this:

Make sure you’re making a new blank project instead of following a predefined pattern.

Once that’s done, you can connect your two services. There's a shortcut _ Connect Service _ button on the homepage of the project that will take you to a form that you must fill out once for OneSignal and once for the CountriesAPI. This is what the latter config looked like:

It’s basically Plug’n’Play. The OneSignal's setup is just as easy because the API key is actually sent along with the JSON body — we'll get to that in a bit.

Next, you’ll need to create the GraphQL mutation that will: 1) look up a country's data from the CountriesAPI and 2) ping OneSignal with the country’s data, plus:

Your API key.
The hash that identifies which device to send the notification to.
the country code to insert into the URL of the CountryFlags API so that you can get automatically add an image to the push notification.

Here's the text of the query in the schema's JSON file:

/*
    Obviously JSON doesn't have comments, but I'm going to add a
    few JavaScript-style comments to explain what each line does
*/

"mutations": { // this is the mutations object in the root of our schema JSON file
    "sendPushNotification": { // the name of this mutation
      "description": "Sends a push notification to the given subscribed user with the given image and content.",
      "args": {
        "type": "object",
        "properties": { 
                    /*
                        these are the arguments coming into the mutation
                        usually you'd make a shape for it and just put "args": "NameOfInputShape"
                        here I've opted to list the arguments in the mutation
                        no reason other than that it feels right
                        we have two arguments defined below, both strings
                    */
          "user": {"type": "string"},
          "countryCode": {"type": "string"}
        },
        "required": ["user", "countryCode"] // both arguments are required
      },
      "shape": "OneSignalResult", 
            /* ^^^^^ is the shape of the result, 
            but we don't really care about our output from onesignal here */
      "resolver": { // aka how we fill in the output steps
        "compose": [ // we're going to do that by following this array of steps
          {
            "name": "graphql:query", // use graphql
            "service": "countries", // to send a ping to the countries service
            "options": {
              "fieldName": "country", // to get this type with the following query
              "selectionSet": "{ name native continent { name } capital currency }"
            },
                        // below, map the `countryCode` from our input to `code` so CountriesAPI will understand
            "argsMapping": {"code": [["get", {"path": "args.countryCode"}]]}
          },
          { // after finishing the request to CountriesAPI, start step 2 of the resolver
            "name": "rest:post", // it's a post request
            "service": "onesignal", // to the onesignal service
            "options": {"path": "notifications"}, // specifically to the /notifications endpoint
            "argsMapping": {
              "json.chrome_web_icon": [ // send an argument called "chrome_web_icon" to onesignal
                [
                  "expressionEval",
                  { // "chrome_web_icon" should be a URL to countryflags.io with the original country code in it
                    "expression": "'https://www.countryflags.io/' + args.countryCode + '/flat/64.png'"
                  }
                ]
              ],
              "json.app_id": [ // set our app_id to a constant (redacted here for obvious reasons)
                ["set", {"value": "MY-REDACTED-ONESIGNAL-APP-KEY"}]
              ],
                            // send our original input user id as the only element in an array called "include_player_ids"
              "json.include_player_ids[0]": [["get", {"path": "args.user"}]], 
              "json.contents.en": [ // send along an object called "contents" with a key "en"
                [
                  "expressionEval",
                  { // set the key "en" to this long message with data from the CountriesAPI
                    "expression": "steps[0].native + '(' + steps[0].name + ') is in ' + steps[0].continent.name + '. In the capital, ' + steps[0].capital + ', the people like to spend ' + steps[0].currency + '.'"
                  }
                ]
              ]
            }
          }
        ],
        "resultsMapping": {"id": [["get", {"path": "steps[1].id"}]]} // send the notification id to our output
      }
    }
  }

That JSON without all the comments is uploaded into TakeShape. We actually just did it through the editor in the project, but you can do it through the terminal as well if you prefer.

To summarize, this process allows you to send this GraphQL query to the TakeShape API mesh endpoint:

mutation {
sendPushNotification (
user: "my-onesignal-user-id-from-the-sdk",
countryCode: "US"
) {
id
}
}

Then, TakeShape will:

Go to the Countries API and get some data about the country we've been given using its abbreviation.
Turn that data into a message and send it along with an image of the country's flag and the device's ID to OneSignal.
Return the ID that OneSignal returns.

Although that may seem tough at first, it is actually fairly intuitive. All you have left to do is to make the GraphQL call in JavaScript!

Another feature we wanted to implement was to add a <select> file on the page with a list of all the country codes, because who really remembers the abbreviation of the country they're looking up? Before we get to that, we first finished setting up the OneSignal SDK.

Part 3: Set Up the OneSignal SDK in Your App

In your Web project folder, navigate to the index.html file. Inside of the head HTML tag, paste the code you previously copied from the OneSignal page:

<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
window.OneSignal = window.OneSignal || [];
OneSignal.push(function() {
OneSignal.init({
appId: "YOUR-APP-ID",
});
});
</script>

Now, locate the SDK files you downloaded on your computer and insert them inside the root folder of your Web app.

After you have inserted the SDK files into your Web project, you'll need to add a <button> to send the notification to yourself. Inside of the <body> tag, add the following code:

<button onclick="sendPush()" id="send-push">SEND PUSH</button>

This button will now call a function called sendPush() that we will create inside of the index.js file. Add the following code to the top of your file. This code contains the API key, the GraphQL endpoint from TakeShape, and the project ID:

const projectID = "YOUR-PROJECT-ID";
const apiKey = "YOUR_API_KEY";
const takeShapeURL = `https://api.takeshape.io/project/${projectID}/v3/graphql`;

Once you have added the code above, it's time for you to use it inside of our sendPush() function. Create the sendPush() function by adding the following code:

const sendPush = async () => {
await fetch(
takeShapeURL,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${apiKey}`
},
body: JSON.stringify({
query: `
mutation {
sendPushNotification (
user: "${await OneSignal.getUserId()}",
countryCode: "${select.value}"
) {
id
}
}
`
})
}
);
};

As you can see, this code is making a POST call to the TakeShape GraphQL endpoint. The input to our POST request is the mutation containing the information needed to display our push notification. The countryCode property is the value from the <select> dropdown. For testing purposes, the value of the user property is going to be your current userID that you get by calling the getUserId() method for the device you are using to view this web application. In other words, you will send a push notification to your device that has registered with OneSignal. Keep in mind that OneSignal allows sending mass push notifications to all the subscribed users of a website.

Allow Web Push Notifications

Run the app and visit your website. You should see the following prompt appear after your chosen time delay interval:

Click on the blue Allow button to enable push notifications on your browser.

If you want to get started by sending a message or two manually, check out this awesome docs page for help.

Step 4: Add Country Code Data to Your Application

Now it's time to fill that <select> with actual data! If you go back into the homepage of your TakeShape project, right above the Connect Service button I clicked earlier, you should see OneSignal connected!

You can click on the _ Countries _ service to get back to the form you originally filled out to add the service in the first place. At the very bottom of that form, there's a button that will let you select queries from the GraphQL service to duplicate inside TakeShape. In the GraphQL service, select the countries query. Doing this will make it so that the countries query from the CountriesAPI is now the Countries_countries query in your API mesh, which you can then use to get a list of countries. That's a little confusing to explain in text, but it's actually the most intuitive way to go about this because this setup will let you choose what queries should be directly accessible through the API mesh. It also avoids creating any conflicts with query names when you start adding more services because they're all namespaced.

With that out of the way, you can just add this to the JavaScript and load the dropdown with the results:

const loadCountries = async () => {
const resp = await fetch(
`https://api.takeshape.io/project/${projectID}/v3/graphql`,
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${apiKey}`
},
body: JSON.stringify({
query: `
query {
Countries_countries {
code
}
}
`
})
}
);
const results = await resp.json();
results.data.Countries_countries.map(x => x.code).forEach(code => {
const option = document.createElement("option");
option.innerText = code;
select.insertAdjacentElement("beforeend", option);
});
};

And that's pretty much it! You can take a look at the GitHub repo for the full code. You can also see the finished product in action.

Let's test it out quick! If you go the page, it should ask you for permission to send push notifications. In the background, that loadCountries function is running, which loads up the dropdown. If you choose one and press the _ Send Push _ button like this:

Then this happens:

Success!

Now, you can keep expanding your code to make use of different features of the OneSignal SDK across your web app. To learn more about the Web Push SDK, visit OneSignal's documentation. If you want to check out more of TakeShape's abilities and how it makes working with APIs much easier in the long run, check out the TakeShape's documentation.

How to Send Push Notifications with the OneSignal REST API

Pato — Mon, 18 Apr 2022 13:00:00 +0000

It’s no secret that push notifications can help you engage and retain app users. In this tutorial, we'll show you how to use the OneSignal REST API using NodeJS.

Using the OneSignal REST API is very useful because it can help you integrate OneSignal into different workflows that your applications may have. The OneSignal REST API is friendly with different technologies including front and backend. Basically, if the tech stack you are using supers API calls, then you can use the OneSignal REST API.

OneSignal & Your Browser's Push API

This tutorial will cover an overview of our OneSignal REST API reference and the usage of our API with a NodeJS server.

Guide Overview

Part 1: OneSignal REST API Overview
REST API reference
Part 2: Push Notification In NodeJS
Setup a NodeJS Application
Send Push Notifications
View Notification insights

This tutorial requires some basic knowledge of NodeJS and usage of REST APIs. Below is a list of platforms that I'm using:

App with OneSignal integrated (mobile, web, or game)
NPM
I’m using NPM version v6.14.11
NodeJS
I’m using NodeJS v16.14.2

Part 1: OneSignal REST API Overview

Send Notifications

The OneSignal Push API allows you to programmatically send push notifications. The push notifications can be sent to different segments (by default you send them to all Subscribed Users) and even specific devices using the User ID. Another cool feature of the OneSignal REST API is the ability to cancel notifications that have been scheduled.

View Notification

Method: POST

Endpoint: https://onesignal.com/api/v1/notifications

Our API can do a lot more than just send a notification and view data from that notification. If you want to learn more about our whole REST API, visit the OneSignal REST API overview page.

Creating Your NodeJS App

Inside your terminal run the following commands to create a new NodeJS project using NPM:

npm init

After entering the previous npm command, answer all the questions that will appear on your terminal. These questions will generate the values of your package.json.

Your package.json file will look like similar to this:

{
    "name": "myapp",
    "version": "1.0.0",
    "description": "",
    "main": "index.js",
    “type”: “module”
    "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
    },
    "author": "",
    "license": "ISC"
}

Setup your NodeJS App

The first thing you need to do is to create an index.js file. This file will contain all code necessary to send and view your notifications.

At the top of this file, add the request npm package. This package will help us make API calls to the OneSignal endpoints in an easier way than doing it with NodeJS natively.

import axios from 'axios';

Now, run npm install axios to add the axios npm package into your project. After you have installed the axios NPM package, add the following three variables to your index.js after the axios import:

const API_KEY = "YOUR ONE SIGNAL API KEY";
const ONE_SIGNAL_APP_ID = "YOUR ONE SIGNAL APP ID";
const BASE_URL = "https://onesignal.com/api/v1";

To get the API KEY and the APP ID from OneSignal, navigate to the OneSignal Dashboard and click on the app you created inside of OneSignal. Once you have selected the app you want to work with, click the S _ ettings _ tab.

On this page, click on Keys & IDs.

Copy the OneSignal App ID and the REST API KEY.

Note: Another quick and easy way to access your OneSignal App ID is by copying it from the URL.

Options Builder

This function is not mandatory in order to use the OneSignal REST API. This function will be in charge of creating the options that you will pass to your API calls. This is a generic function that will build the JSON object based on the parameters that you have passed.

Parameters:

@param {string} method
@param {string} path
@param {object} body

Returns:

@returns {object} options

const optionsBuilder = (method, path, body) => {
    return {
        method,
        'url': `${BASE_URL}/${path}`,
        'headers': {
        'Content-Type': 'application/json',
        'Authorization': `Basic ${API_KEY}`,
        },
        body: body ? JSON.stringify(body) : null
    };
}

Create Notification

Create a push notification and send it to the users of your app.

Method: POST

Endpoint: https://onesignal.com/api/v1/notifications

Postman Collection

Parameters:

@param {object} body
@returns {object} response

const createNotication = async (data) => {
const options = optionsBuilder("post","notifications", data);
try {
        const response = await axios(options);
        return response.data;
    } catch (error) {
        console.error(error);
        return error;
    }
}

Here’s a sample body object:

const body = {
    app_id: ONE_SIGNAL_APP_ID,
    included_segments: ['Subscribed Users'],
    data: {
        foo: 'bar',
    },
    contents: {
        en: 'Sample Push Message',
    },
};

View Notification

Create a push notification and send it to the users of your app.

Method: GET

Endpoint: https://onesignal.com/api/v1/notifications

Postman Collection

Parameters:

@param {string} notificationId

const viewNotifcation = async (notificationId) => {
    const path = `notifications/${notificationId}?  app_id=${ONE_SIGNAL_APP_ID}`;
        const options = optionsBuilder("get", path);
    try {
        const response = await axios(options);
        console.log(response.data);
    } catch (error) {
        console.log(error);
    }
}

Run Your Code

At the end of the file, add the following lines of code. The first createNotification() function will return the notification's basic information when you send push notifications. I’m using this function to call the OneSignal API. As you can see, I’m using object destructuring to grab the notification ID from the notification object returned from the createNotification(), that will be used to call the viewNotifcation() function.

const {id} = await createNotication(body);
await viewNotifcation(id);

Feel free to test other OneSignal REST API endpoints and let us know what you think!

Join the OneSignal Developers Community

Want to learn more about the OneSignal products and other technologies? Join our OneSignal Developers Community!

Stay Connected

Follow our OneSignal Developers Twitter to learn more about the OneSignal product, technical tips, and the latest events from our developers.

How to Add Push Notifications into an iOS App

Pato — Mon, 14 Mar 2022 18:36:55 +0000

Push Notifications are a great tool to engage and retain your users. In this tutorial, we’ll show you how to add push notifications to your iOS app for free using OneSignal.

Guide Overview

Creating an Apple iOS Push Certificate
Setting up Your OneSignal Account
Setting up Push Notification in iOS
Linking an External User ID to the OneSignal Player ID
Allowing Notifications
Sending Notificaitons

Getting Started

First off, let’s create an Xcode project as a demo in order to use the SDK. This is going to be an UIKit app, but you can use SwiftUI as well.

Creating an Apple iOS Push Certificate

Before sending push notifications, you'll need to generate an iOS Push Certificate. To do that, you'll need to ask Apple to give you a production certificate. Go to the developer portal, click on Certificates, IDs & Profiles , and then click on Identifiers. Look for the app ID you just created in Xcode. If you can’t find it, click on the + button in order to add it.

Locate your app ID or add it by clicking the "+" button

On the _ Identifiers _ and Profiles page, the App IDs option should already be selected. Simply click on the _ Continue _ button and you’ll be redirected to the type of app you want to create the ID for. Click on Continue once again.

Check that "App IDs" is selected before pressing continue.

Now you’ll land on the App ID registration page where you’ll see two form fields for Description and Bundle ID. Fill them with the correct information, being sure that the Bundle ID exactly matches the one you create previously in Xcode.

Enter an app "Description" and "Bundle ID."

Once you click the _ Continue _ button, you should see a review page. Click on _ Register _ and voilà — you should now see your app in the _ Identifiers _ list.

Click "Register" to register your app.

Your app is now viewable from the Identifiers menu.

Next, you'll need to generate a certificate for OneSignal. To do so, open the Keychain Access app, select Certificate Assistant from the drop-down menu, and click on Request a Certificate From a Certificate Authority. This option just means that your machine is going to be the one with the private key for this particular certificate.

Select "Certificate Assistant" and "Request a Certificate From a Certificate Authority."

A window should appear asking you to provide certificate information. Enter your email address and check the _ Save to disk _ option. You will also be prompted to choose where you want to save the certificate request. Make sure to save it somewhere safe.

Now, you'll need to go back to Apple's developer portal and create a certificate. To do so, click on the + button.

You’ll be redirected to the _ Certificates _ creation page. Scroll down on this page until you see the Services header. Under this header, select the option entitled Apple Push Notification service SSL (Sandbox & Production) and then click the _ Continue _ button.

On the next page, it’ll ask you for the App ID that you want to create the certificate for. Select the one you created earlier from the drop-down menu and click the _ Continue _ button.

Select your App ID to create a new Apple Push Notification certificate.

Next, you’ll be prompted to upload the Certificate Signing Request. Choose the file you saved previously and click _ Continue._

Upload your Certificate Signing Request.

If everything works just fine, you should be redirected to the download page. Click on the _ Download _ button to download it and double-click to open it in the Keychain Access app.

Download your push notification certificate.

In the _ Keychain Access _ app, navigate to the _ My Certificates _ tab and find the certificate you just create which has your app bundle ID in the name. Right-click on it to see the options, then click _ Export _ from the menu that appears_._ It’ll prompt you to provide the location of the certificate. Select somewhere on your machine and type a password for the certificate.

Setting Up Your OneSignal Account

In order to add push notifications to your iOS app, you'll need to have a OneSignal account. If you don't have a OneSignal account, you can easily create a free account or simply log in to an existing account to get started.

iOS Configuration

In the OneSignal dashboard, click on the _ New App/Website _ button.

Configure a new app/website in OneSignal.

On the next page, type the name of your app and select the Apple iOS (APNs) option for the platform and click on the _ Next: Configure Your Platform _ button.

Select Apple iOS (APNs) as your chosen platform.

You’ll be prompted to upload the Apple certificate file you created in the first part of this tutorial. Locate the certificate on your machine, type in the password for the certificate, then click the _ Save & Continue _ button.

Upload your Apple push notification certificate.

Next, you'll be prompted to choose your target SDK. Select Native iOS as the target SDK and click on _ Save & Continue _ button at the bottom of the screen.

Select Native iOS as your target SDK.

In this final step, under 1. Install the SDK, you should see the App ID provided by OneSignal. Copy it somewhere where it's easy to retrieve — you’ll use it in the code later. Once you've saved the ID, you can click on _ Done _.

Congratulations, you’ve successfully configured your OneSignal project and you’re almost ready to send your first push notification 🥳 ! The last step is to go back to our iOS project and configure it so that it can receive notifications from OneSignal.

Setting up Push Notifications in iOS

Go back to the iOS project you created earlier and select the main target. Under the Signing & Capabilities tab, click on the + Capability button, then select Push Notifications. This will enable your app to receive push notifications from OneSignal.

Next, you'll need to add a Notification Extension to the app. Go back to the General tab and click the plus icon at the bottom of the Targets section.

You’ll be prompted to select the template for your new target. Select _ Notification Service Extension _ then click _ Next._

In the next window, use _ OneSignalNotificationServiceExtension _ as the name of the extension (as the docs suggest) and click the _ Finish _ button.

A message will appear asking if you want to activate the scheme. You don’t want to activate the push notification scheme because you just want to run your application (not the notification), so click on the Cancel button.

The notification extension will come with a NotificationService.swift. Open it and replace the content with the code below:

import OneSignal
import UserNotifications

class NotificationService: UNNotificationServiceExtension {
    var contentHandler: ((UNNotificationContent) -> Void)?
    var receivedRequest: UNNotificationRequest!
    var bestAttemptContent: UNMutableNotificationContent?

    override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
        self.receivedRequest = request
        self.contentHandler = contentHandler
        self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

        if let bestAttemptContent = bestAttemptContent {   
            OneSignal.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
        }
    }

    override func serviceExtensionTimeWillExpire() {
        if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
            OneSignal.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
            contentHandler(bestAttemptContent)
        }
    }  
}

If you build the project, you’ll get a compilation error since the project doesn’t yet know the OneSignal module. To fix that error, you'll need to install the module via Swift Package Manager.

In Xcode, go to _ File _ > _ Add Packages _ and enter the package URL https://github.com/OneSignal/OneSignal-XCFramework and click on Add Package.

Add the OneSignal XCFramework in Xcode.

This will add the OneSignal library to the main target. You also need to add the OneSignal library to the extension target. Select the OneSignalNotificationServiceExtension target. Under the Frameworks and Libraries section, click on the _ + _ button.

_Add the OneSignal library to the extension target in Xcode. _

After clicking on the + button, a menu should appear. The OneSignal library should be one of the choices in this list. Select OneSignal and click _ Add._

If you build and run, the error should have disappeared.

Build Succeeded message in Xcode.

There's one last step you must complete to finish the setup process: configuring the SDK inside your AppDelegate. To do so, open your AppDelegate, import the OneSignal library, and paste the following initialization code to didFinishLaunchingWithOptions:

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

    OneSignal.setLogLevel(.LL_VERBOSE, visualLevel: .LL_NONE)

    OneSignal.initWithLaunchOptions(launchOptions)
    OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID")

    OneSignal.promptForPushNotifications(userResponse: { accepted in
      print("User accepted notifications: \(accepted)")
    })

    return true
  }

In this code snippet, you'll need to provide the App ID OneSignal generated for you earlier. You can find this information in your project’s dashboard under the _ Keys & IDs _ menu. Because this is sensitive data, make sure to obscure it in some way so that it isn’t visible directly in the source code.

Linking an External User ID to the OneSignal Player ID

OneSignal creates and stores device and channel level data under a unique OneSignal ID called the player_id. A single user can have multiple player_id records based on how many devices, email addresses, and phone numbers they use to interact with your app or website.

Create a method that generates a random string as your external user ID and register it to OneSignal. Your final AppDelegate should look like this:

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

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

    return true
  }

  private func initializeOneSignal() {
    OneSignal.setLogLevel(.LL_VERBOSE, visualLevel: .LL_NONE)

    OneSignal.initWithLaunchOptions(launchOptions)
    OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID")

    OneSignal.promptForPushNotifications(userResponse: { accepted in
      print("User accepted notifications: \(accepted)")
    })
  }

  private func setupExternalId() {
    let externalUserId = randomString(of: 10)

    OneSignal.setExternalUserId(externalUserId, withSuccess: { results in
      print("External user id update complete with results: ", results!.description)
      if let pushResults = results!["push"] {
        print("Set external user id push status: ", pushResults)
      }
      if let emailResults = results!["email"] {
        print("Set external user id email status: ", emailResults)
      }
      if let smsResults = results!["sms"] {
        print("Set external user id sms status: ", smsResults)
      }
    }, withFailure: {error in
      print("Set external user id done with error: " + error.debugDescription)
    })
  }


  private func randomString(of length: Int) -> String {
    let letters = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
    var s = ""
    for _ in 0 ..< length {
      s.append(letters.randomElement()!)
    }
    return s
  }
}

Allowing Notifications

The moment of truth has arrived — it's time to put your setup work to the test by sending a notification. To begin, launch your app directly on your iOS device. You should see the following prompt appear asking if you would like to receive notifications from your app. Click on the blue Allow button to enable push notifications on your device.

Sending Notifications

It’s now time to send your first push notification! To do so, login to your OneSignal account and navigate to the _ Dashboard _ tab. On the Dashboard page, click on the blue button at the top right corner entitled +_ New Push _.

Click the "+New Push" button to create a new notification.

You will be redirected to a new window that will allow you to create and customize your push notification.

Under the section entitled _ Audience _, make sure that _ Send to Subscribed Users _ is selected. Then, create your message by adding your message title, content, and image. Because this is the first notification your subscribers will receive, you may choose to craft a simple welcome message to confirm that they've been subscribed and reinforce the value that notifications will provide.

Under the _ Delivery Schedule _ section, select _ Immediately _ and _ Send to everyone at the same time _ to send to all your current push subscribers. If you have just finished setting up your OneSignal account, chances are you're the first and only subscriber. If your app is heavily trafficked and other users have already opted in to receive push notifications, you may want to select Send to a particular segment(s) to test your message out on a select audience. When you're ready to send your message, click on the blue _ Review and Send _ button at the bottom of the screen.

A small popup will appear prompting you to review your message. Once you are satisfied, click on the blue _ Send Message _ button.

You should receive a push notification on your iOS device! 🚀

Get Support & Share Your Feedback

To learn more about our iOS mobile push SDK, please visit our iOS push iOS Mobile Push SDK documentation.

We'd love to know what you think and answer any additional questions you have. Ping us on the OneSignalDevs Discord server to share your experience. We appreciate any insight you can share to help us better serve you!

To stay in the loop with the latest product updates and innovations, follow the OneSignal Developers Twitter. For additional support and dev inspiration, tap into our global developer community.

This post was guest authored by Ibrahima Ciss

How to Add Push Notifications to a Flutter App

onesignaldevs — Mon, 14 Mar 2022 18:35:30 +0000

Push notifications have proved to be one of the most effective ways to enhance your user experience, improve app engagement, and boost retention. In this tutorial, we’ll show you how to integrate push notifications in your iOS and Android apps with minor configuration changes using the OneSignal Flutter SDK. In no time, you'll be able to send out transactional and promotional push notifications to users for free!

If you are a Flutter developer and want to leverage push notifications to engage with your users, follow along to add this amazing functionality to your apps.

Guide Overview:

Part 1: Set Up Your OneSignal Account
Part 2: Creating a Flutter App

Part 1: Set Up Your OneSignal Account

To begin, log in to your OneSignal account or create a free account. Then, click on the blue button entitled _ New App/Website _ to configure your OneSignal account to fit your app or website.

Add your app name, select _ Google Android _ if the target is Android devices or select _ Apple iOS _ if the target is iOS devices. Then click, Next: Configure Your Platform.

For iOS, you will need to add an iOS push certificate. If you're not sure about this step, read OneSignal's instructions on how to generate an iOS push certificate.

Apple iOS (APNs) Configuration in OneSignal

For Android, you will need to enter Firebase Server Key and Server ID that you can get by creating a new project on Firebase Console.

Google Android (FCM) Configuration in OneSignal

To find the Firebase service key, log in to the Firebase console and click on Add Project.

Add the name of your project and turn off Enable Google Analytics for this project if you want, then click on Create Project.

Click _ Create project _ to save the new entry, then click _ continue _.

You’ll be directed to the project dashboard where you have to click on the Setting icon next to _ Project Overview _ and click on _ Project Settings _ from the menu that appears.

Navigate to the project settings menu in the Firebase console.

In the Cloud Messaging tab, you’ll be able to find the Firebase Server Key and Server ID. Navigate back to your OneSignal dashboard and copy and paste those values into the appropriate fields under OneSignal Google Android(FCM) Configuration like this:

Input your Firebase Server Key and Sender ID in OneSignal.

After clicking on Save & Continue , you’ll be asked to select your target SDK. Choose Flutter.

Choose Flutter as your target SDK.

Click Save & Continue again and then click Done at the bottom of the screen.

View your app ID in OneSignal to finish the Google Android FCM configuration process.

Now, you should see your app dashboard on OneSignal under the _ Settings > Platforms _ tab. On this page under _ Native App _ _ platforms , you should see an **_Active** tag next to _ Google Android, _ which means you’re ready to send notifications to users using the Android version of your Flutter app. If you followed the iOS setup, you should see an _ Active _ tag next to _ Apple iOS _.

An "Active" tag is displayed next to Google Android in the OneSignal dashboard.

Part 2: Creating a Flutter App

So the first thing you need to do after creating a new Flutter project is to add the onesignal_flutter dependency. To do that, visit pub.dev and search for onesignal_flutter.

Shows onesignal_flutter 3.2.7 in pub.dev.

Add the latest version of onesignal_flutter to pubspec.yaml under the dependencies section with the version number from pub.dev.

Now open main.dart and remove MyHomePage() class (or just its contents).

Remove the content of MyHomePage() from main.dart.

Create a new dart file named home.dart (or continue in the main.dart file) and create a stateful widget by the name Home like this:

class Home extends StatefulWidget {
const Home({Key? key}) : super(key: key);
@override
_HomeState createState() => _HomeState();
}
class _HomeState extends State<Home> {
@override
Widget build(BuildContext context) {
return Container();
}
}

Next, build a simple UI by adding a few widgets like Container, Column and Text in the Home class.

@override
Widget build(BuildContext context) {
return Scaffold(
body: Container(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
crossAxisAlignment: CrossAxisAlignment.center,
children: const [
Text("Hello"),
],
),
),
);
}

Now you can add the OneSignal App ID which you can find in your OneSignal dashboard under the Keys & IDs tab.

Copy the OneSignal App ID and add it into your Flutter app in main.dart as a constant.

static final String oneSignalAppId = "16090413-4b70-4c0b-a9f4-dd43c445ccee";

Then add SDK initialization code to your XXX.

Future<void> initPlatformState() async {
   OneSignal.shared.setAppId(oneSignalAppId);
   OneSignal.shared
       .promptUserForPushNotificationPermission()
       .then((accepted) {});
 }

Also, initialize state.

@override
 void initState() {
   super.initState();
   initPlatformState();
 }

Complete Code(main.dart)

import 'package:flutter/material.dart';
import 'package:onesignal_flutter/onesignal_flutter.dart';

class Home extends StatefulWidget {
 const Home({Key? key}) : super(key: key);

 @override
 _HomeState createState() => _HomeState();
}

class _HomeState extends State<Home> {
 @override
 void initState() {
   super.initState();
   initPlatformState();
 }

 static final String oneSignalAppId = "16090413-4b70-4c0b-a9f4-dd43c445ccee";
 Future<void> initPlatformState() async {
   OneSignal.shared.setAppId(oneSignalAppId);
   OneSignal.shared
       .promptUserForPushNotificationPermission()
       .then((accepted) {});
 }

 @override
 Widget build(BuildContext context) {
   return Scaffold(
     body: Container(
       child: Column(
         mainAxisAlignment: MainAxisAlignment.center,
         crossAxisAlignment: CrossAxisAlignment.center,
         children: const [
           Text("Hello"),
         ],
       ),
     ),
   );
 }
}

Run your Flutter app on your physical device or emulator.

In case you recieve compileSdkVersion error then go to your app-level build.gradle file and update compileSDKVersion to 31.

defaultConfig {
// TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
applicationId "com.example.flutter_onesignal"
minSdkVersion 16
compileSdkVersion 31
targetSdkVersion 30
versionCode flutterVersionCode.toInteger()
versionName flutterVersionName
}

If you get Kotlin Version error then go to your build.gradle file in the root of your Android directory and upgrade your Kotlin_version to the latest version (ext.kotlin_version = '1.5.10')

For the iOS version, there’s are some additional steps that need to be completed. The first one is to add an iOS service extension.

The OneSignalNotificationServiceExtension allows your application (in iOS) to receive rich notifications with images and buttons, along with badges and Confirmed Deliveries.

The first step is to navigate to your Flutter project's iOS folder and open the .xcworkspace file in Xcode. You can use the open ios/Runner.xcworkspace command in the terminal to do the same.

Then select File > New > Target.

Select Notification Service Extension and press Next.

Add the product name as OneSignalNotificationExtension and change the language to _ Object-C _ or Swift according to your needs. The team account should be your account or your organization’s account.

Add the product name as OneSignalNotificationExtension in Flutter.

Click the _ Finish _ at the bottom right corner of the window, but when prompted to “Activate” scheme click on _ Cancel _.

Click "Cancel" when prompted to activate the scheme.

By canceling, you are keeping Xcode set to debug your app rather than using the extension. If you select _ Activate _ by accident, you can simply switch back to debug your app in Xcode (next to the Play button).

Now, open the Xcode project settings and select the _ OneSignalNotificationServiceExtension _ target. Under the _ Deployment info _ section on this page, select iOS 10.0 as the target unless there are any reason for using higher versions.

Now, close the Xcode project and go back to your Flutter development IDE. In the /ios directory of your project, open the Podfile and add the following lines outside of the main target (they should be at the same level as your main target):

target 'OneSignalNotificationServiceExtension' do
use_frameworks!
pod 'OneSignalXCFramework', '>= 3.4.3', '< 4.0'
end

Also, make sure to uncomment the platform line at the top of the Podfile. It can be iOS version 9.0 or higher according to your needs.

Now Open the terminal, cd to the ios directory, and run pod install.

If you see the error below, remove # from the above in front of use_frameworks! and try again.

- Runner (true) and OneSignalNotificationServiceExtension (false) do not both set use_frameworks!.

Open the <project-name>.xcworkspace file. In your project, in the OneSignalNotificationServiceExtension/ folder, open NotificationService.m.

Replace the whole file contents with the following code for Objective-C:

#import <OneSignal/OneSignal.h>
#import "NotificationService.h"
@interface NotificationService ()
@property (nonatomic, strong) void (^contentHandler)(UNNotificationContent *contentToDeliver);
@property (nonatomic, strong) UNNotificationRequest *receivedRequest;
@property (nonatomic, strong) UNMutableNotificationContent *bestAttemptContent;
@end
@implementation NotificationService
- (void)didReceiveNotificationRequest:(UNNotificationRequest *)request withContentHandler:(void (^)(UNNotificationContent * _Nonnull))contentHandler {
   self.receivedRequest = request;
   self.contentHandler = contentHandler;
   self.bestAttemptContent = [request.content mutableCopy];

   //If your SDK version is < 3.5.0 uncomment and use this code:
   /*
   [OneSignal didReceiveNotificationExtensionRequest:self.receivedRequest
                      withMutableNotificationContent:self.bestAttemptContent];
   self.contentHandler(self.bestAttemptContent);
   */

   /* DEBUGGING: Uncomment the 2 lines below and comment out the one above to ensure this extension is excuting
                 Note, this extension only runs when mutable-content is set
                 Setting an attachment or action buttons automatically adds this */
   // NSLog(@"Running NotificationServiceExtension");
   // self.bestAttemptContent.body = [@"[Modified] " stringByAppendingString:self.bestAttemptContent.body];

   // Uncomment this line to set the default log level of NSE to VERBOSE so we get all logs from NSE logic
   //[OneSignal setLogLevel:ONE_S_LL_VERBOSE visualLevel:ONE_S_LL_NONE];
   [OneSignal didReceiveNotificationExtensionRequest:self.receivedRequest
                      withMutableNotificationContent:self.bestAttemptContent
                                  withContentHandler:self.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.

   [OneSignal serviceExtensionTimeWillExpireRequest:self.receivedRequest withMutableNotificationContent:self.bestAttemptContent];

   self.contentHandler(self.bestAttemptContent);
}
@end

For Swift, replace it with:

import UserNotifications

import OneSignal

class NotificationService: UNNotificationServiceExtension {

   var contentHandler: ((UNNotificationContent) -> Void)?
   var receivedRequest: UNNotificationRequest!
   var bestAttemptContent: UNMutableNotificationContent?

   override func didReceive(_ request: UNNotificationRequest, withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void) {
       self.receivedRequest = request
       self.contentHandler = contentHandler
       self.bestAttemptContent = (request.content.mutableCopy() as? UNMutableNotificationContent)

       if let bestAttemptContent = bestAttemptContent {
           //If your SDK version is < 3.5.0 uncomment and use this code:
           /*
           OneSignal.didReceiveNotificationExtensionRequest(self.receivedRequest, with: self.bestAttemptContent)
           contentHandler(bestAttemptContent)
           */

           /* DEBUGGING: Uncomment the 2 lines below to check this extension is excuting
                         Note, this extension only runs when mutable-content is set
                         Setting an attachment or action buttons automatically adds this */
           //OneSignal.setLogLevel(.LL_VERBOSE, visualLevel: .LL_NONE)
           //bestAttemptContent.body = "[Modified] " + bestAttemptContent.body

           OneSignal.didReceiveNotificationExtensionRequest(self.receivedRequest, with: bestAttemptContent, withContentHandler: self.contentHandler)
       }
   }

   override func 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.
       if let contentHandler = contentHandler, let bestAttemptContent = bestAttemptContent {
           OneSignal.serviceExtensionTimeWillExpireRequest(self.receivedRequest, with: self.bestAttemptContent)
           contentHandler(bestAttemptContent)
       }
   }

}

You also need to enable an App Group to use Confirmed Deliveries and increment/decrement Badges through push notifications. For that, you can follow the iOS SDK App Groups setup guide to add the OneSignal App Group in your app.

Now you need to enable push capability for iOS apps. Open your .xcworkspace file in Xcode.

In the main app target, select Signing & Capabilities > All > + Capability and then search "push." Double-click on _ Push Notifications _ to enable it.

Next, enable Background Modes and check Remote Notifications.

Now you are ready to send notifications from the OneSignal dashboard!

Back in your OneSignal dashboard, click on Messages in the top navigation menu and select _ Push _ from the sub-menu. Click the +New Push button to create your first notification.

Note: Notifications are enabled on Android devices by default if you have disabled your notifications, make sure you enable them again. If you're sending a notification to an iOS device, you will need to opt-in to notifications in your app settings.

Click the "+New Push" button in your OneSignal dashboard.

You will be redirected to a new window that will allow you to customize your push notification. Under _ Audience _, make sure that _ Send to Subscribed Users _ is selected. Then, create your message by adding your message title, content, and image. Because this is the first notification your subscribers will receive, you may choose to craft a simple welcome message to confirm that they've been subscribed and reinforce the value that notifications will provide.

Under the _ Delivery Schedule _ section, select _ Immediately _ and _ Send to everyone at the same time _ to send to all your current push subscribers. If you have just finished setting up your OneSignal account, chances are you're the first and only subscriber. If your app or website is heavily trafficked and other users have already opted in to receive push notifications, you may want to select Send to a particular segment(s) to test your message out on a specific audience.

Specify the audience for your push notification in OneSignal.

Add your message title and copy and preview how your message looks on your target device.

When you're ready to send your message, click on the blue _ Review and Send _ button at the bottom of the screen.

A small popup will appear for you to review your message. Once you are satisfied, click on the blue _ Send Message _ button. You should receive a push notification on your device! 🚀

You’re done 🎊!

You’ll receive the notification on your physical device that you used to run your Flutter app or on the emulator.

After the message sends, you'll be directed to the Delivery page where you can view the send report and track engagement.

Still have questions?

Check out our complete OneSignal Flutter SDK Documentation.

This post was guest authored by Akanksha Singh.

iOS Web Push Notification support is coming soon in 2022

George Deglin — Tue, 01 Feb 2022 22:36:38 +0000

On January 27, 2022, Apple seeded the first Beta of iOS 15.4 featuring several updates— including one that we've been looking forward to for a long time.

iOS 15.4 is expected to introduce many new features, including support for Face ID with a Mask, new emojis, and updates to built-in apps such as Notes and AppleTV.

However, the most exciting addition is experimental support for iOS web push notifications!

The setting to enable Web Notifications support in Safari (WebKit) Preferences can be seen on an iOS 15.4 device running in the Xcode Device Simulator

Web push notifications are a popular communication channel used by more than 8% of top websites. They provide an essential mechanism for websites to send timely and personalized messages to users.

An example of Web Push notifications being used to send sports and Covid news stores on a both Windows and an Android Device

Nearly every operating system supports this valuable communication channel. Unfortunately, until recently, Apple was a significant outlier and showed little interest in allowing web push on iOS devices. In the past, Apple has faced pushback for falling behind on supporting modern web APIs, including web push.

Considering that Apple owns 52% of the mobile market in the United States and a similarly large market share worldwide, this limitation has dramatically slowed the adoption and utility of web push notifications. As a result, websites have resorted to pressuring users to download apps or provide either an email or SMS number to receive messages.

This latest addition to iOS 15.4 Beta is a promising sign that Apple will finally enable web push support in Safari on iOS and allow its use in other iOS browsers such as Chrome and Firefox.

In our tests of this new Beta capability in iOS 15.4, we've determined that web push is disabled by default, and unfortunately, enabling it does not yet work. However, this the introduction of this new option and the newly introduced iOS web push APIs are strong signs that Apple is actively working on introducing full web push support.

Although the public launch of iOS 15.4 is slated for April 2022, web push support likely won't be available until later, possibly in iOS 16. If this prediction is correct, we'll see iOS web push introduced with the public launch of iOS 16 in September 2022.

That might be a while to wait, but nonetheless we're incredibly excited for the opportunities this will unlock for better and more user-friendly mobile web experiences. The OneSignal team is following this news closely and will ensure that all OneSignal customers are prepared to seamlessly leverage web push on iOS when it's available.

How to Add Push Notifications to a Vue App

William Shepherd — Wed, 22 Dec 2021 23:08:44 +0000

This guide will help you quickly add push notifications to your Vue application (for free) with the OneSignal-Vue plugin. To follow this tutorial, you will need to have some working knowledge of Vue 2 and its tooling. The focus of this guide is to demonstrate how to push a notification to a Vue app. It does not cover how to create a new Vue app; for that, please refer to Vue's documentation on how to create a new Vue project.

Guide Overview

Part 1: Set Up Your OneSignal Account
Web Configuration
Part 2: Configure Your Vue Application
Initializing the OneSignal Vue Plugin
Using the Plugin on Components
Share Your Feedback

Part 1: Set Up Your OneSignal Account

To begin, log in to your OneSignal account. If you don't have a OneSignal account, you can easily create a free account.

Web Configuration

To begin, log in to your OneSignal account and click the _ New App/Website _ button on the dashboard.

Name your app and select Web as your platform.

Click the button labeled, Next: Configure Your Platform so you can choose how you'd like to integrate into your Vue app.

In the Web Configuration window, select the Custom Code integration option and provide a name you'd like to use to refer to your website along with the site URL where the app is hosted. If you don't know your site URL yet, don't worry —you can set it to your localhost and update it once you deploy your Vue app.

In the meantime, enable _ Auto Resubscribe _ by moving the toggle to the right to ensure that your dev build always gets notified even when you clear your browser’s data. You'll also need to enable _ Local Testing _ so that you can receive push notifications on your dev machine.

Click the Save button to continue the configuration process.

In the 4. Upload Files section, click the Download OneSignal SDK Files button to get the service workers needed to receive push notifications or download the SDK files from our Github repository.

Part 2: Configure Your Vue Application

Now, you can follow the instructions that ship with the onesignal-vue package on npm.

Install onesignal-vue in your Vue project using your preferred package manager.

yarn add onesignal-vue
npm install --save onesignal-vue

Extract the service worker files from the archive you downloaded from the OneSignal dashboard and copy the files into your project’s public directory.

Initializing the OneSignal Vue Plugin

Now you can set up the plugin by modifying main.js to import the package and initialize the plugin by setting the appId property to your OneSignal application identifier.

import Vue from "vue";
import OneSignal from "onesignal-vue";

import App from "./App.vue";

Vue.config.productionTip = false;

Vue.use(OneSignal);

new Vue({
  render: h => h(App),
  beforeMount() {
    this.$OneSignal.init({
      appId: "<You OneSignal application identifier",
      allowLocalhostAsSecureOrigin: true,
    });
  },
}).$mount("#app");

Using the Plugin on Components

Once initialized, use the plugin on any component you like. For this tutorial, we're going to call it from the HelloWorld.vue component to present a slide prompt that allows visitors to your site to opt-in to push notifications.

Find the <script> tag and set a callback for the beforeCreate lifecycle hook in the exported object.

import OneSignal from "onesignal-vue";
import HelloWorld from "./components/HelloWorld.vue";

export default {
  name: "App",
  components: {
    HelloWorld,
  },
  beforeCreate() {
    this.$OneSignal.showSlidedownPrompt();
  },
};

The integration is complete. You can test it out by starting the app using yarn serve then opting into push notifications.

You should have received a test push notification indicating the integration is successful.

Share Your Feedback

We'd love to know what you think of this plugin and answer any additional questions you have. To connect with us, create an issue on GitHub or ping us on the OneSignalDevs Discord server to share your experience. We appreciate any insight you can share to help us better serve Vue.js users!

To stay in the loop with the latest product updates and innovations, follow the OneSignal Developers Twitter. For additional support and dev inspiration, tap into our global developer community.

>> Connect with the OneSignal Developer Community

How To Add Android Push Notifications to a React Native Expo App

Pato — Wed, 22 Dec 2021 21:32:10 +0000

It’s no secret that push notifications can help you engage and retain app users. In this tutorial, we'll show you how to integrate with the React-OneSignal NPM package to leverage push notifications in your React app for free.

OneSignal & Your Browser's Push API

A mobile push API gives mobile applications the ability to receive messages from a server whether or not the app is in the foreground. This lets you deliver asynchronous notifications and updates to users who opt-in, resulting in better engagement with timely new content.

This tutorial will cover how to integrate the new React Native Expo OneSignal Plugin to add mobile push notifications into your application using our typical setup process. Part one of this guide covers the OneSignal setup process. Part two of this guide covers how to integrate OneSignal with React using our npm package.

Guide Overview

Part 1: Set Up Your OneSignal Account
Google Android FCM Configuration
Part 2: Set Up Push Notifications in React Native Expo
Create Your React Native App
Install the OneSignal Expo Plugin
Configure the Plugin
Run and Build Your Application
Send Push Notifications to Android Devices
Connect With Our Developer Community

This tutorial requires some basic knowledge of React Native (Expo). I'm using the Expo CLI to generate my project and NodeJS version 14.16. Additional React

Additional Setup Resources:

React Native (Expo) plugin Sample Ap

Part 1: Set Up Your OneSignal Account

To begin, log in to your OneSignal account or create a free account. Then, click on the blue button entitled _ New App/Website _ to configure your OneSignal account to fit your app or website.

Insert the name of your app or website. Select _ Google Android _ as your platform.

Click on the blue button entitled, _ Next: Configure Your Platform _.

Google Android FCM Configuration

It’s time to configure your Android app using a Firebase Server key. All Android apps require this key and the server ID in order to send push notifications. If you don’t have the Firebase Server API Keys, take a look at our documentation to learn how to generate a Firebase server API key.

Now select your target SDK. We'll take you through the steps to get your first user and send your first test notification later in this guide.

In the next screen that appears, you will see your App ID — copy that App ID because you will use it inside of your Expo Application. DO NOT click to Check Subscribed Users or Done yet.

Part 2: Set Up Push Notification in React Native Expo

Create Your React Native App

Inside of your terminal run the following commands to create a new React project using Create.

Expo App:

expo init onesignal-rn-expo

When asked, select any of the options under the Managed Workflow. In my case, I selected the first option, which is blank .

cd onesignal-rn-expo
expo start

For additional guidance, check out Expo's official documentation on how to create a new Expo App.

Install the OneSignal Expo Plugin

Inside of your project folder, open your terminal and run the following command to install the OneSignal Expo Plugin package.

expo install onesignal-expo-plugin

After installing the signal-expo-plugin, install now the react-native-onesignal plugin by running the following command.

yarn add react-native-onesignal

Even though onesignal-expo-plugin defines react-native-onesignal as a dependency and it gets put into the node_module it will make sure the native parts get built.

If you forgot to run the following command after you have built your project, you can fix this by running expo prebuild — clean. This should delete android and ios and do a clean native build, then run the yarn add react-native-onesignal.

Configure the Plugin

Inside the app.json/app.config.js file, add the plugin to the plugin array:

App.json

{
    "plugins": [
        [
            "onesignal-expo-plugin",
            {
                "mode": "development",
                "devTeam": "91SW8A37CR"
            }
        ]
    ]
}

App.config.js

export default {
...
    plugins: [
        [
            "onesignal-expo-plugin",
            {
                mode: process.env.NODE_ENV || "development",
                devTeam: "91SW8A37CR"
            }
        ]
    ]
};

Plugin Options:

mode: used to configure APNs environment entitlement.
"development"
"production"
devTeam: *optional* — used to configure Apple Team ID. You can find your Apple Team ID by running expo credentials:manager.

Example:

{
    "extra": {
        "oneSignalAppId": "<YOUR APP ID HERE>"
    }
}

You can then access the value to pass to the setAppId function:

import OneSignal from 'react-native-onesignal';
import Constants from "expo-constants";
OneSignal.setAppId(Constants.manifest.extra.oneSignalAppId);

Alternatively, pass the OneSignal App ID directly to the function:

OneSignal.setAppId("YOUR-ONESIGNAL-APP-ID");

Run and Build your Application

expo prebuild
# Build your native iOS project
$ expo run:ios
# Build your native Android project
expo run:android

Send Push Notifications to Android Devices

I recommend you run the application on an actual Android device to test the notifications. To do so, you will need to connect your Android device and enable developer mode.

Once you have opened the application on your device, the device will be automatically subscribed to the notification. Now, your device will be able to receive notifications sent by OneSignal.

To complete the setup process, return to your OneSignal dashboard to the point at which you previously left off. Click on the _ Check Subscribed Users _ and a green message will appear like the one in the image below.

Click on the _ Done _ button.

Send Your First Notification

It’s time to send your first push notification! To do so, log in to your OneSignal account and navigate to the _ Dashboard _ tab. On the dashboard page, click on the blue button that says _ New Push _.

Note: Notifications are enabled on Android devices by default if you have disabled your notifications, make sure you enable them again.

A small popup will appear for you to review your message. Once you are satisfied, click on the blue _ Send Message _ button. You should receive a push notification on your device! 🚀

Now, you can keep expanding your code to make use of different features of the OneSignal SDK across your Expo app bypassing the OneSignal variable to different components.

To learn more about the OneSignal Expo plugin, visit our React Native (Expo) push SDK documentation.

Connect with Our Developer Community

To stay in the loop with the latest product updates and innovations, follow the OneSignal Developers Twitter and join our Discord server. Learn more about the OneSignal developer community and how to stay connected by following the link below.

>> Learn About the OneSignal Developer Community

Effective TypeScript for React Applications

Graham Marlow — Mon, 13 Sep 2021 17:33:00 +0000

TypeScript and React are excellent in combination. When you sprinkle React’s expressive component model with a little strong typing, you get fewer bugs and an improved developer experience.

That said, the amount of techniques and nuances baked into the TypeScript/React combo can be overwhelming. TypeScript offers so much flexibility in structuring your React components that it’s hard to know what’s best in which situation. Those familiar with JavaScript may find themselves banging their heads against stubborn compiler warnings. Others may dread the boilerplate mountain that looms over every component.

No matter your level of experience with TypeScript, this guide is here to help you out. We’ve listed below our best practices for working with TypeScript and React, which are based on the same patterns used in our core product.

Use Interfaces Until You Need a Type

For the most part, you can use type aliases and interfaces interchangeably, as the difference between the two is subtle. You can extend existing interfaces with new properties, whereas type aliases are off-limits after declaration. Despite their similarity, it’s still useful to define a pattern so that you’re using the two styles consistently.

Here at OneSignal, we follow the heuristic “use interface until you need to use features from type". We recommend interfaces because they offer a familiar syntax for inheritance that mirrors ES2015 classes. In contrast, types are used to alias primitive values or create unions from other types.

type ButtonKind = "primary" | "secondary";

interface Props {
  kind: ButtonKind;
}

Unions Over Enums

Unlike most TypeScript features, [enum] is not a type-level addition to JavaScript but something added to the language and runtime. Because of this, it’s a feature which you should know exists, but maybe hold off on using unless you are sure.

—TypeScript Handbook

Union types and enums tend to occupy the same space in React in that they both enforce that a particular prop must be one value of a given set. However, we recommend union types over enums for a number of reasons:

They are compiler-only constructs, so they won't end up in your application's JS bundle.
They are extensible to other union types.
They are less verbose.

// Avoid enums:
enum ButtonKind {
  PRIMARY = "primary",
  SECONDARY = "secondary",
}

// Prefer union types:
type ButtonKind = "primary" | "secondary";

// Extensible to other union types:
type ExtendedButtonKind = ButtonKind | "tertiary";

Now, there are a few caveats to consider with this rule.

For one, const enum is a compile-time only enum that doesn’t increase the size of your JS bundle. Unfortunately, const enum is a disabled keyword for certain build tools, like Babel or esbuild.

You should also consider that union types and enums are not syntactically the same. You can reference the value of an enum by its declaration, avoiding direct references to a string literal. If this behavior is desirable, look to regular JS objects instead. With a handy utility type from type-fest, you can achieve the same behavior.

const ButtonStyle = {
  PRIMARY: "primary",
  SECONDARY: "secondary",
} as const;

type ButtonStyleType = ValueOf<typeof ButtonStyle>;

Extending Native HTML Elements

TypeScript ships with tons of helper types that cut down boilerplate for common React idioms. These types are particularly useful when extending native HTML elements like button or input, where you’ll want to maintain the component's original props to ensure extensibility.

Start by implementing a Button component in the two most important use-cases: clicking the button and defining its text. When typing everything manually, you get the following result:

import React from "react";

interface Props {
  children: React.ReactNode;
  onClick: () => void;
}

function Button({ children, onClick }: Props) {
  return <button onClick={onClick}>{children}</button>;
}

The first helper type to use here is React.PropsWithChildren, which automatically adds the children prop to the component:

import React from "react";

type Props = React.PropsWithChildren<{
  onClick: () => void;
}>;

function Button({ children, onClick }: Props) {
  return <button onClick={onClick}>{children}</button>;
}

Button is looking better, but the component still has to redefine props that are native to the HTML element, like onClick. This is a big problem for foundational components like Button that make up your application’s design system, as their props will grow wildly with their usage.

// This list tends to grow quickly!
type Props = React.PropsWithChildren<{
  onClick: () => void;
  type: "submit" | "button" | "reset" | undefined;
  disabled: boolean;
  // ...
}>;

Luckily, TypeScript has another utility designed for this exact purpose.

ComponentPropsWithoutRef is a generic type that supplies props for built-in React handlers and native HTML attributes. By passing in "button" as the template, you specify that the component is extending the HTML button element.

import React from "react";

type Props = React.ComponentPropsWithoutRef<"button">;

function Button({ children, onClick, type }: Props) {
  return (
    <button onClick={onClick} type={type}>
      {children}
    </button>
  );
}

The result is a component that is clean and extensible. If additional props are needed, swap the type for an interface:

import React from "react";

interface Props extends React.ComponentPropsWithoutRef<"button"> {
  specialProp: number;
}

function Button({ children, onClick, type, specialProp }: Props) {
  // ...
}

Type Refinement and Disjoint Unions

Disjoint unions (or discriminated unions) are a powerful feature that can help you refine the component props of complex structures. In short, they allow your component to support multiple variants of a shared interface.

Consider a Button component that has several theme variations, such as "primary" and "secondary". You can express this type as a string and pass it down as props.

interface Props {
  kind: string;
}

function getStyles(kind: string) {
  switch (kind) {
    case "primary":
      return styles.primary;
    case "secondary":
      return styles.secondary;
    default:
      throw new Error("invalid button kind");
  }
}

function Button({ kind }: Props) {
  const styles = getStyles(kind);
  // ...
}

While this implementation is simple, it presents significant problems.

For one, you can pass any string value into the component props, even though only "primary" and "secondary" are implemented by the component. TypeScript won't warn you that any other value throws an error.

// This passes compiler checks, yet throws an application error!
function App() {
  return <Button kind="not-a-style">click me!</Button>;
}

You can instead switch string to a union type, which offers much-needed improvements. The union type informs TypeScript of all possible values for kind, preventing any unhandled cases.

type ButtonKind = "primary" | "secondary";

interface Props {
  kind: ButtonKind;
}

function getStyles(kind: ButtonKind) {
  switch (kind) {
    case "primary":
      return styles.primary;
    case "secondary":
      return styles.secondary;
    // Default case is no longer needed!
  }
}

function Button({ kind }: Props) {
  const styles = getStyles(kind);
  // ...
}

Looking back at the component instance that is passed an invalid string literal, TypeScript now offers a helpful error:

// Error: Type '"not-a-style"' is not assignable to type 'ButtonKind'
function App() {
  return <Button kind="not-a-style">click me!</Button>;
}

Union types are great at refining props for primitive values. But what about more complex structures?

Consider that the "primary" button requires a special method, specialPrimaryMethod, that is not supported by the “secondary” variant. The component calls this special method when handling a click.

type ButtonKind = "primary" | "secondary";

interface Props extends React.ComponentPropsWithoutRef<"button"> {
  kind: ButtonKind;
  specialPrimaryMethod?: () => void;
}

function Button({ kind, onClick, specialPrimaryMethod, children }: Props) {
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    if (kind === "primary") {
      if (specialPrimaryMethod) {
        specialPrimaryMethod();
      }
    } else {
      onClick?.(e);
    }
  };

  return <button onClick={handleClick}>{children}</button>;
}

Although this component compiles, the type definition of props doesn’t inform the TypeScript compiler when specialPrimaryMethod is permitted. The TypeScript compiler thinks that both “primary” and “secondary” allow the method, and that the method is optional in either case.

To further demonstrate why this is problematic, take a look at the following instances of the component. The TypeScript compiler considers all of them valid, even though some of them conflict with the intended implementation.

// Correct use-case
<Button kind="primary" specialPrimaryMethod={doSpecial}>...

// Invalid use-case: specialPrimaryMethod shouldn't be optional
<Button kind="primary">...

// Invalid use-case: secondary shouldn't support specialPrimaryMethod
<Button kind="secondary" specialPrimaryMethod={doSpecial}>...

This is where the disjoint union comes in handy. By splitting apart the interfaces for the “primary” variant and the “secondary” variant, you can achieve better compile-time type-checking.

type ButtonKind = "primary" | "secondary";

// Build separate interfaces for Primary & Secondary buttons
interface PrimaryButton {
  kind: "primary";
  specialPrimaryMethod: () => void;
}

interface SecondaryButton {
  kind: "secondary";
}

// Create a disjoint union
type Button = PrimaryButton | SecondaryButton;

// Add built-in HTML props to the disjoin union
type Props = React.ComponentPropsWithoutRef<"button"> & Button;

// You can no longer destructure props since specialPrimaryMethod
// doesn't always exist on the object.
function Button(props: Props) {
  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
    if (props.kind === "primary") {
      // No extra if check needed!
      props.specialPrimaryMethod();
    } else {
      props.onClick?.(e);
    }
  };

  return <button onClick={handleClick}>{props.children}</button>;
}

The additional type refinement provided by the disjoint union now appropriately throws compile-time errors for invalid cases.

// All good!
<Button kind="primary" specialPrimaryMethod={() => {}}>foo</Button>

// Error: Property 'specialPrimaryMethod' is missing
<Button kind="primary">click me!</Button>

// Error: Type '{ ... specialPrimaryMethod: () => void; }' is not assignable
<Button kind="secondary" specialPrimaryMethod={() => {}}>click me!</Button>

Don’t Overuse Disjoint Unions

Disjoint unions are a powerful technique that enable general-purpose components. However, take care not to overuse them as they can lead to highly complex components.

Anytime you reach for disjoint unions, pause and consider whether the single component should instead be separated into two.

Accessible Components With Polymorphism

Polymorphic components are great for tuning markup for accessibility.

Consider a Container component that applies some styles to a div. You may want to use this Container component in situations that are better described by HTML5 elements like aside or section.

Rather than duplicating the Container component for slight alterations in its JSX, create a polymorphic component. This is as simple as including a new prop, as, that accepts a union of HTML element strings.

import React from "react";

type Props = React.PropsWithChildren<{
  as: "div" | "section" | "aside";
}>;

function Container({ as: Component = "div", children }: Props) {
  return <Component className={styles.container}>{children}</Component>;
}

The destructured alias, { as: Component }, is a convention that helps illustrate that the prop is a React component and not just a string.

The Container component now supports different HTML5 elements to better fit its use-case.

<Container as="section">
  <p>section content</p>
</Container>

Watch Out for These Bad Practices

Using `defaultProps`

Defining defaultProps on function components is marked for deprecation. You should instead assign defaults with prop destructuring:

Prefer

interface Props {
  color?: string;
}

function Button({ color = "red" }: Props) {
  /* ... */
}

Avoid

type Props = { color: string } & typeof defaultProps;

const defaultProps = { color: "red" };

function Button(props: Props) {
  /* ... */
}

Button.defaultProps = defaultProps;

Using the Non-Null Assertion Operator

The non-null assertion operator subverts TypeScript’s ability to check null values. Despite how easy it is to type, this operator can cause a ton of harm. Let TypeScript do its job!

In this case, you should instead rely on refinement or narrowing and avoid overriding the TypeScript compiler.

Prefer

const liveSafely = (x?: number) => {
  if (typeof x !== 'number') {
    throw new Error('number expected')
  }
  return x.toFixed(2)
}}

Avoid

const liveDangerously = (x?: number) => {
  return x!.toFixed(2);
};

Raising Exceptions for Exhaustive Cases

There are few cases that call for raising an exception within a React component, since it renders a blank screen if handled improperly. You can avoid catastrophic failures with Error Boundaries, but in most cases throwing an exception is unnecessary.

Instead, default to the closest acceptable user interface.

Prefer

switch (props.kind) {
  case "primary":
  default:
    return { color: "red" };
}

Avoid

switch (props.kind) {
  // ...
  default:
    throw new Error("unsupported option");
}

At OneSignal, we love empowering developers to refine their workflow and build great software. We hope these patterns help evolve your React and TypeScript codebase.