# Push Notifications in Text Express

## Analysis and Design:

> Library research, Available products research, Community research, SWOT analysis, Guideline conformity analysis, IT architecture sketching, Brainstorming, Multi-criteria decision making	

### Current situation

Currently in Text Express there are **local** notifications, which mainly serve to increase the retention of the game by alarming the players to get back into the game.

![Example local push notification](/files/-Mc3kE2QJZxq97sgSDOe)

These notifications are called **local**, because they are **hard-coded** in the client (game) and are set to **go off after a specific amount of time**. This however, is very limiting and not as useful, as having the ability to trigger a **remote/push** notification**,** **whenever you want** and **without modifying the code** in your game every time you want to add or remove a notification.

### Graduation assignment

For my graduation project I have received the assignment to implement **remote/push** notification service in Text Express, with the view to allow **dynamic (***not hard-coded and triggered by time***) notifications** and **strengthen and improve the communication between the developers and the players.** 

### Clarifications and design

#### Which 3rd party push notifications services can I use?

First, I did library research on the internet about what possibilities there are for push notification services. A requirement for me was of course that the 3rd party service supports and can be integrated into a Unity project. After some reading, I have found out that the following are very powerful solutions, which could achieve the task I was given:

1. [OneSignal](https://documentation.onesignal.com/docs/onesignal-platform)
2. [Get Social](https://docs.getsocial.im/guides/notifications/introduction/)
3. [Playfab](https://docs.microsoft.com/en-us/gaming/playfab/features/engagement/push-notifications/quickstart)

#### OneSignal vs. GetSocial vs. Playfab

Other studios in Gamehouse have already been using the **OneSignal** and **Playfab** Push Notifications in their games, so I had a conversation with some of them, in order to extract as much information as possible about the difficulties they have encountered and the experience they had with those services.

![Talk with Kim- "Bed and Breakfast" designer, about her experience with Playfab Push Notifications. ](/files/-M_w06JdkcQockbJz0Jw)

![Chat with Carlos- "Delicious World" developer, about his experience with OneSignal](/files/-Mc4HSXQWQqX9chnEwd6)

After having the conversations with the Gamehouse employees and having the topic reserached by myself, I have created the following table to present the pros and cons of each push notification service: 

![Pros and Cons of Playfab, Get Social and OneSignal](/files/-Mc4RL9K9aCpP8JdDjZv)

Having **Playfab** being very **unstable** when a big group of people is targeted and having **Get Social** being **expensive** to use, after some discussions with my technical and design mentors, I have chosen to go with **OneSignal** for a Push Notification system in Text Express.

#### How to implement OneSignal?

In order to implement OneSignal fast and successfully, I have researched what has to be done and have created a plan to follow:

* [x] Creating the Text Express project in [OneLink ](https://app.onesignal.com/apps/8026d180-8b59-4790-86bf-29bb770e9141/settings/configure/google-android?newApp=true)platform.
* [x] Configure the OneLink project in the platform- [set up keys and IDs](https://documentation.onesignal.com/docs/generate-a-google-server-api-key).
* [x] Integrate the OneSignal[ Unity SDK](https://documentation.onesignal.com/docs/unity-sdk-setup#step-10---implement-a-soft-prompt-in-app-message-for-ios).

#### How does OneSignal work after implementation?

After reading how [**OneSignal subscribing of users** ](https://documentation.onesignal.com/docs/users)works, it was determined that after integrating the OneSignal SDK in Unity, all **Android** devices which start the game, will **automatically** be subscribed for receiving Push Notifications from the service: 

![Automatic subsribing for Android devices](/files/-Mc6AFtjX0LfgPNFs9Q6)

#### How does OneSignal work for IOS devices?

As IOS Devices have more user privacy, the subscribing to OneSignal is *not* automatic. All IOS devices, must have a **prompt screen** shown, asking for **the consent of the user**, before having the device subsrcibed to OneSignal:

![Design for the future when IOS Devices are being targeted](/files/-Mc6AJrjEjsV6e0LjnNe)

As Text Express is not planning to release the game for IOS devices yet, this case will be out of my scope for the graduation assignment. 

#### Can Push Notifications be created and sent from the Client/In-game or it can be done only from the OneSignal Console?

After [researach](https://documentation.onesignal.com/docs/unity-sdk) I have found out that I can not only send the notifications to all subscribed users from the OneSignal console, but also ***create and send notifications from the Client***/In-game.

#### What proof of concept can I make for sending Push Notifications from the client?

As you can also send push notifications from the client/In-game and not only from the OneSignal Console, I wanted to find a way to integrate this functionality, as useful and as meaningful as possible. That is why I suggested the following:

![Discussion on what proof of concept could be done for sending Push notifications from the in-game.](/files/-Mc3r5WCf6_oBxQv00-q)

#### Is it possible to transfer the segments from Playfab to OneSignal?

Segmentation is a very important factor in mobile games, as it groups similar players into one group and you can offer specific experiences for each different group. For example:

![How segmentation works: Different segments, see different game data/values](/files/-Mc4r3EjsaDJVOd-rJzf)

Although, OneSignal offers very good user segmentation on its own, the segmentation of players in Text Express is handled by Playfab. That is why, if we want to send different push notifications, to specific Playfab segments, I have to find a way to use the Playfab segments in OneSignal.

First, I was looking into the possibility to create new OneSignal segments, based on the Playfab segments, using the OneSignal[ server REST APIs](https://documentation.onesignal.com/reference/create-segments). Although, this is possible, the segments from Playfab would have to be transferred to OneSignal, every time a segment changes:

![Transfering the segments from Playfab to OneSignal is not a viable solution  ](/files/-Mc4zr9tjIUAIbM2HndJ)

After diving deeper for a solution, I have found out that when a new device is being subscribed to OneSignal, you can also specify an "**external\_user\_id"** to that device. Then, when you [**Create Push Notifications**](https://documentation.onesignal.com/reference/create-notification), you can target devices, by their "**external\_user\_id**":

![Design: Setting up \[external\_user\_id\] to Playfab ID and how to create a notification to a Playfab Segment](/files/-Mc6AQSTOwMwE-txcNHx)

## Design

> IT architecture sketching, Decomposition, IT Architecture Scetching

### Integrating the Push Notifications in the "Friend Referral" system

In order to create a useful proof of concept of sending Push Notifications from the Client, I decided to do the following: Whenever a player receives a **Personal Notification** and has a pending reward waiting for him, I can send a **Push Notification** to that player, notifying him that: "*You have successfully referred a friend, there is a reward waiting for you in Text Express*":

![Improving the Personal Notification feature, by adding push notifications.](/files/-Mc8Zr3-dgvcd8Wip7qf)

### Creating push notification templates

From the research I have done during the Analysis phase, I have found out that I can create **Push Notification Templates** in the OneSignal console. **Templates** are visually pre-configured designs of push notifications, which can be used over and over again and you can use them by specifying their **template\_id:**

![Constructing a template in the OneSignal Console](/files/-Mc9H2Xq7LCtVjH-PBs6)

![Plan on how I am going to construct the Push Notifications in the Friend Referral system](/files/-Mc93EJaQQav7MgzcSPe)

## Realization

> Static Code analysis, Simple A/B test, Best good bad practices, Literature study, Brainstorming 

### OneSignal Implementation

Setting up Text Express in the OneSignal console and then implementing the OneSignal Unity SDK in the project, was very easy, as I have followed the [plan created during the Analysis phase](/social-and-community-features-in-text-express/features/remote-push-notifications-in-text-express.md#how-to-implement-onesignal). Just like the implementation of the [Deeplinks](/social-and-community-features-in-text-express/features/deeplinking.md#navigation-deeplinks) and the[ Social Authentication](/social-and-community-features-in-text-express/features/social-authentication-in-text-expess.md#class-design) feature, I have followed the **Single Responsible Principle** while creating the Push notifications class, which improved the maintainability and the comprehension of the class.

The implementation, was tested by sending a push notification from the OneSignal console to all subscribed users and it worked successfully:

![My devices has automatically subscribed to the OneSignal service and has successfully receieved PN.](/files/-McApjb-Yoa96XxvKgLZ)

### Integrating Push Notifications in the "Friend Referral" feature

After successfully configuring Text Express in the OneSignal console and successfully Implementing the OneSignal SDK I have started following the design and plan created during the [Design Phase](/social-and-community-features-in-text-express/features/remote-push-notifications-in-text-express.md#integrating-the-push-notifications-in-the-friend-referral-system) for integrating the push notifications in the "Friend Referral" feature flow.

#### Improving the Push Notification Templates

While following the design for the push notification, I have created several different **push notification templates** and for each new or changed template I had to include it in the **Playfab TitleData templates list**:

![Playfab Title Data templates list had to be constantly updated](/files/-Mc9Mui8HnVcXkEEh4oJ)

In order to make it easier for the designers, who will be the ones creating the OneSignal Push Notification templates, I have decided to configure and define the templates in the **Playfab TitleData** only.

![Fields defining a Push Notification only in Title data](/files/-McB3Wx58oYvM-RWMakc)

This solution to **defining Push Notification templates** is better, as it is more flexible and eases the flow of creating a Push Notification template. Now, there is only one place (only the Playfab **Title Data**), where notifications will be defined and not 2 (in the **OneSignal Console** and then adding the **template\_id** in the **Title Data**).

#### Targeting external\_user\_id from the client doesn't work

When the design was implemented it was time for testing. However, when trying to send a push notification from the client side by targeting a device by its **external\_user\_id**, nothing was being received on my subscribed device:

![A/B test with code to see which one is received](/files/-McAxV1IfwU8GajeaGMX)

After doing a [research ](https://documentation.onesignal.com/docs/unity-sdk#postnotification)on the internet it was found out that:  

>   *Note: You can only use* **`include_player_ids`** *as a targeting parameter from your app. Other target options such as* **`include_external_user_ids`** *require your OneSignal App REST API key which can only be used from your server.*

The latter comment meant that the design I had created wouldn't work and that it has to change so that the Text Express **backend server** is sending the Personal Notifications and not the game (client): 

![New design for creating a push notification during the Friend Referral flow](/files/-McB4TrTblKr_0h5CHUr)

### After diving deeper 

#### Changing external\_user\_id when transferring progress from one device to another using the Google/Facebook authentication services.

Whenever a person transfers his progress using the [Google and Facebook authentication features ](/social-and-community-features-in-text-express/research/design-for-login-with-authentication-flow.md#flow-diagram)the **Playfab ID** and **Device ID** of his account get mixed, therefore they become wrong in the OneSignal user records.\
Because of that I have changed the code of the authentication flow, to assign a new **external\_user\_id** every time an account progress is being transferred, so that the records in OneSignal are always in sync with the records in Playfab.

![Extra step added to handle OneSignal data sync, when transferring progress with Google or Facebook](/files/-McBAeibuBhv8uM7wqdB)

## Evaluation

> Brainstorming

### Easy communication with players

Now Text Express' developers can send push notifications to specific or to all of their players, whenever they want and without having to update the code of the game. Having this opportunity, different marketing campaigns can be run, in order to prompt the players back into the game and increase the retention rate of the game.

### Easy communication between players

Whenever, you have received a reward in Text Express or something important happened to your account, you were not able to know that immediately, but you would know that when you start the game. That is not the case anymore! Now, when there are push notifications integrated into the "**personal notifications**" feature, whenever a personal notification is received in the player's account, a **Push Notification** will be sent to this player's device, saying: *"There is a new personal notification waiting for you!":*

![Successful notification received when a friend installed Text Express for the first time](/files/-McDDNbL10TIdnMSeJfz)

After having this system up and running my mentor said that: *Such system and feature may be overlooked at first, but it incentives the players to log in the game more often and eventually get hooked to the game faster.*

### Future works

**Customization on Push Notifications:** 

As OneSignal offers a lot of customization options for its Push Notifications, the artists of Text Express can have a look at how to customize the notifications on all devices following this [guide](https://documentation.onesignal.com/docs/customize-notification-icons).

#### Apple handling and integration

As IOS was not in the scope of my graduation internship I haven't Implemented the OneSignal functionality for apple devices to accept to subscribe for a Push Notification. In order to do that in a good way this is a very good [read/research ](https://adriancrook.com/analysis-opt-best-practices-ios/)to be taken into account.

{% content-ref url="/pages/-MXYhnZTzB70NQ86B2-j" %}
[Evaluation](/social-and-community-features-in-text-express/evaluation.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://lyudmil.gitbook.io/social-and-community-features-in-text-express/features/remote-push-notifications-in-text-express.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.