# Push Notifications by One Signal

## Overview

Push notifications are one of the biggest advantages of mobile apps over mobile websites since they can send messages to users without the app being open. 

When a user first opens an app with push notifications enabled they receive an alert prompting them to enable push notifications. Once they accept they are a subscriber of your app's push notifications. 

## Thunkable + OneSignal

Thunkable utilizes the services of [OneSignal](https://onesignal.com/) to facilitate push notifications from your app. OneSignal is a free service that supports unlimited devices and notifications. You can learn more about their features here: [OneSignal pricing page](https://onesignal.com/pricing).

<div align="left"><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LAn5scXl2uqUJUOqkJo%2F-Ldj4ctHr-LxEZeEHWqr%2F-Ldj7G9zd1BhYt-cIqo-%2Fonesignaldemo.png?alt=media&#x26;token=dff423fe-286a-47a9-8065-79a12ca33a03" alt="One Signal is the world leader in push notifications and they offer their service for free. "></div>

To send push notifications to your app's users, you must link your Thunkable app to your OneSignal apps (iOS and/or Android). Once you've added your OneSignal App IDs into Thunkable, the work in Thunkable is done, and the remainder of the management takes place in third-party platforms (OneSignal, Apple Developer, and Firebase, depending on the platform).&#x20;

{% hint style="info" %}
This feature may only be available for Creators on certain Thunkable plans. Please refer to our pricing page for more information: [Thunkable pricing](https://thunkable.com/pricing).
{% endhint %}

Push notifications are one of the biggest advantages that mobile apps have over mobile websites, since they can send messages to users without the app being open.&#x20;

However, annoying notifications---those that are irrelevant and too frequent---can be dismissed or blocked easily.  We highly recommend sending notifications only when the content is relevant to the user. Examples of this include an e-commerce app notifying users of a sale, or a game notifying users of new levels and features.

{% hint style="warning" %}
**Push Notifications cannot be tested with the Thunkable Live app on iOS**\
You can test Push Notifications on iOS by publishing your app to TestFlight and downloading it from there.
{% endhint %}

## Add Push Notifications to your app

To add Push Notifications to your app :

1. Drag and drop the component onto any screen.&#x20;

<div align="left"><figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FuuGwxHSWEDSPidof1spO%2Fimage.png?alt=media&#x26;token=5a1d373d-3e09-4b2a-b0e0-c9a5ab2516b5" alt=""><figcaption></figcaption></figure></div>

That's it.  There are no blocks needed.&#x20;

2. Click **Push Notification** at the bottom of the screen

<div align="left"><figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FUyJteJEhQ28e29Wmh5SI%2Fimage.png?alt=media&#x26;token=9076ee4f-00f8-45fc-84b2-3d6fd0b04963" alt=""><figcaption></figcaption></figure></div>

3. The Push Notification settings modal opens. This is where you will enter your OneSignal Android App ID and OneSignal iOS App ID to configure the connection between OneSignal and your Thunkable project.&#x20;

<div align="left"><figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FLBuWTRLNMb1gSLUVsD5J%2Fimage.png?alt=media&#x26;token=484bd641-14f8-4ea2-8bc5-ef2d120752e8" alt=""><figcaption></figcaption></figure></div>

## Properties

| Property                          | Description                                                                  | Data Type  |
| --------------------------------- | ---------------------------------------------------------------------------- | ---------- |
| Android App ID                    | App ID for Android from OneSignal                                            | Text       |
| iOS App ID                        | App ID for iOS from OneSignal                                                | Text       |
| Geolocation Enable (Android Only) | Toggle whether your end user is asked for permission to share their location | True/False |

### Geolocation Permissions

OneSignal allows you to push messages to users in certain locations. You will need permission from your end users to register their location to use this feature. \
You can toggle whether you request geolocation permissions from your end users in the Push Notifications settings panel.

4. The remainder of this document will assist you with:

* [Creating a OneSignal Account](https://docs.thunkable.com/v/snap-to-place/push-notifications-by-one-signal#create-a-onesignal-account)
* [Creating a OneSignal App](https://docs.thunkable.com/v/snap-to-place/push-notifications-by-one-signal#create-a-onesignal-app)
* [Configuring for Android](https://docs.thunkable.com/v/snap-to-place/push-notifications-by-one-signal#android-configuration)
* [Configuring for iOS](https://docs.thunkable.com/v/snap-to-place/push-notifications-by-one-signal#ios-configuration)

## Create a OneSignal Account

1. Go to [**OneSignal**](https://onesignal.com/).
2. Click **Sign Up**.
3. Create your account and complete the OneSignal onboarding.

## Create a OneSignal App

1. If you didn't create an app as part of the OneSignal onboarding, navigate to your OneSignal dashboard and click **+ New App/Website**.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FpdhJ43rt5yFaxTlCdVjc%2Fspaces_-LAn5scXl2uqUJUOqkJo-84897653_uploads_dlqCH9NxWRxTaixLLG4L_Screen%20Shot%202022-02-16%20at%2011.webp?alt=media&#x26;token=b84dfd67-e789-416e-94b9-70b0ecc252f3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you intend to send push notifications to your app's users on Android and iOS you will need to create a new app in OneSignal for each, Android and iOS.
{% endhint %}

2. Enter your **app name**. We recommend including the platform in your app name, for example, Employee Directory - Android or Employee Directory - iOS.&#x20;
3. Select **Apple iOS (APNs)** or **Google Android (FCM)**.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2F89HkDQpF5hGztFB3COAy%2Fspaces_-LAn5scXl2uqUJUOqkJo-84897653_uploads_Aqw1PLzt5bx3hrmmPNvn_Screen%20Shot%202022-02-16%20at%2011.webp?alt=media&#x26;token=73de02f2-5b14-4a10-b974-fcef2ada998d" alt=""><figcaption></figcaption></figure>

4. Click **Next: Configure Your Platform**.
5. Follow the platform-specific configuration instructions below:

* [Android Configuration](https://docs.thunkable.com/v/snap-to-place/push-notifications-by-one-signal#android-configuration)
* [iOS Configuration](https://docs.thunkable.com/v/snap-to-place/push-notifications-by-one-signal#ios-configuration)

## Android Configuration

A Google Service Account is a special type of account from Google that applications use to make authorized calls to a variety of APIs, including Firebase Cloud Messaging APIs. For more details, see Google's own [documentation on Service Accounts](https://cloud.google.com/iam/docs/service-account-overview). In order to send push notifications to Android devices, you will need a Service Account to generate a private key for OneSignal to utilize.

1. If you don't already have one, create a [**Firebase**](https://firebase.google.com/) account. Instructions for getting started with Firebase are available here: [Firebase Account Setup](https://docs.thunkable.com/sign-in#getting-started).
2. Follow OneSignal's instructions to generate Firebase Cloud Messaging API Credentials for sending Android App Notifications here: [Android: Firebase Credentials](https://documentation.onesignal.com/docs/generate-a-google-server-api-key).<br>

   <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><p>To continue sending messages in 2024, you need to provide updated authentication credentials from Firebase for all apps created in OneSignal before September 1, 2023:</p><ol><li>In your Firebase project, go to <strong>Project settings</strong> and the <em><strong>Service accounts</strong></em> tab to download your private key JSON.</li><li>In your OneSignal App Settings, upload the private key file you just downloaded</li></ol><p>More information on these steps is available here: <a href="https://documentation.onesignal.com/docs/generate-a-google-server-api-key">Android: Firebase Credentials</a>.</p></div>
3. Select **Native Android** as your target SDK.
4. Click **Save & Continue**

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FGmfmreGmHhdiVNOOFzQ6%2Fnative%20android.png?alt=media&#x26;token=1116a07c-050c-49ef-983b-280f48e7831f" alt=""><figcaption></figcaption></figure>

5. Copy **Your App ID**.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2Fhyft1nlVX7nePaGY6p0t%2Fspaces_-LAn5scXl2uqUJUOqkJo-84897653_uploads_oK2HVteARJTooDWWZmj6_app-id.webp?alt=media&#x26;token=cd41dd2e-27ad-4d77-992a-bfa8873e33ca" alt=""><figcaption></figcaption></figure>

6. In the **Android App ID** field, paste **Your App ID** that you copied from OneSignal in step 3.&#x20;

<div align="left"><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FPt4SNRDOvpQH751MNJ0g%2Fonesignal%20push%20notification%20APP%20id.png?alt=media&#x26;token=b155d9a6-bcc4-4a65-98ee-78ac77c177b7" alt=""></div>

7. Click the **Live Test on Device** icon and open the Thunkable Live app on your device.
8. Return to your **OneSignal** tab.&#x20;
9. Click **Check Subscribed Users.**

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FtTrfaPJkrtXeXB3n3VJd%2Fspaces_-LAn5scXl2uqUJUOqkJo-84897653_uploads_F95MDKGvhTuCGyMNK5J0_OneSignal%20-%20Check%20Subscribed%20Users.webp?alt=media&#x26;token=716f3501-2dc8-4150-9ce3-5403a4061283" alt=""><figcaption></figcaption></figure>

10. If the configuration is successful, you will see a congratulations message.
11. Click **Done**.&#x20;

### Android Testing

To test Android push notifications, download the app to your Android device and send a test message through OneSignal to see the push notification in action.

### Toggle Location Permission (Android Only)

OneSignal is a powerful choice of push provider. With their platform, you can setup for your users to be pushed notifications [based on their locations](https://documentation.onesignal.com/docs/location-triggered-event). This is optional, however. This also means you need to make a conscious decision as to whether or not to track your Android users geographical locations. These tracking data can be accessed via the OneSignal dashboard. \
\
This feature can be toggled on and off in the Push Notifications settings by clicking on the icon at the bottom of your design screen. <br>

![](https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FDEXyPjobh8rfQkE75PxH%2FScreen%20Shot%202021-12-20%20at%203.54.28%20PM.png?alt=media\&token=b5fa323c-a4f0-4f80-a223-53902d4eb23c)

{% hint style="warning" %}
If you enable **Geolocation Permissions**, when you publish your app, ensure that you indicate that you're tracking location when you publish your app.
{% endhint %}

## &#x20;iOS Configuration

### Generate a p8 Certificate

1. Follow OneSignal's instructions to generate a p8 certificate: [iOS: p8 Token-Based Connection to APNs](https://documentation.onesignal.com/docs/establishing-an-apns-authentication-key).
2. When you get to the section titled "Provisioning Profiles," return to these instructions.

### Add Push Notifications to the App Identifier

1. In your Apple Developer account, select **Identifiers** under the Certificates, IDs & Profiles heading.
2. Select your app from the list of Identifiers.
3. Scroll down the list of app capabilities, and place a checkmark next to **Push Notifications**.
4. Click **Save**.
5. Select your app from the list of Identifiers again.
6. Scroll down the list of app capabilities, until you get to **Push Notifications** again.
7. Click the associated **Configure** button.
8. Under Production SSL Certificate, click **Create Certificate**.
9. Under Upload a Certificate Signing Request, click **Choose File**.
10. Select the **Certificate Signing Request (CSR)** you downloaded from Thunkable as part of the publishing process.
11. Click **Continue**.
12. Click **Download** to download your iOS certificate.

### Download your Provisioning Profile

1. Access your Apple Developer account’s [Profiles](https://developer.apple.com/account/resources/profiles/list).&#x20;
2. Select your app from the list of Profiles.
3. Click **Edit**.
4. Click **Save**.
5. Click **Download**

### OneSignal

1. In OneSignal, select **Native iOS** as your target SDK.
2. Click **Save & Continue**.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2Faa2LhpZngYRXBpgq3qyI%2Fonesignal%20iOS%20configuration.webp?alt=media&#x26;token=ba166701-17d8-4357-ad3f-697314b6620d" alt=""><figcaption></figcaption></figure>

3. Copy **Your App ID**.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FmjWVG4HCeB3C6DRD4lzE%2Fonesignal%20iOS.webp?alt=media&#x26;token=ea5f59d5-b558-47f4-819f-5396f85c2c85" alt=""><figcaption></figcaption></figure>

4. Return to the Blocks tab of your Thunkable project. Do not close the OneSignal tab.&#x20;
5. Click on the icon at the bottom of your design screen to open the Push Notifications dialog and paste this ID into the iOS App ID field.

<div align="left"><figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2FPt4SNRDOvpQH751MNJ0g%2Fonesignal%20push%20notification%20APP%20id.png?alt=media&#x26;token=b155d9a6-bcc4-4a65-98ee-78ac77c177b7" alt=""><figcaption></figcaption></figure></div>

### Generate a Provisioning Profile

You require a new provisioning profile with push notifications enabled to publish to the App Store. See OneSignal's instructions here: [Generate a Provisioning Profile](https://documentation.onesignal.com/docs/establishing-an-apns-authentication-key#create-your-profile).

### iOS Testing

To test iOS push notifications, you have to publish to TestFlight. This requires the provisioning profile with push notifications enabled.&#x20;

## Send Push Notifications

Once you have your platforms configured in OneSignal you can create and sent push notifications to your app's users. Follow OneSignal's instructions here: [Sending Messages](https://documentation.onesignal.com/docs/sending-notifications#sending-push-notifications-from-onesignal-dashboard).

## Blocks

### Functions

#### User ID

The first time your app is opened on a new device, it is automatically assigned a unique push notification user ID. This block returns the user's push notification user ID that can be used to send a notification to a specific user with a web API call.

<figure><img src="https://689802330-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUe3rgJfvQYLrpDR1HfWv%2Fuploads%2Ff1QpnAuaAFcRr2eK5qCi%2Fpush%20notification%20block.png?alt=media&#x26;token=a28cf33b-f743-4c02-b347-09ba7e5d96d2" alt=""><figcaption></figcaption></figure>