Introduction

GameSparks lets you send push notifications using Firebase Cloud Messaging (FCM), iOS push notifications, and Windows Phone push notifications. By default, our push notifications are configured for English and use English language characters. However, there might be occasions where you will need to send or want to send a push notification to your players in their native language. In these cases, the content of the notification might need to use non-English language characters. GameSparks does not offer an out-of-the-box solution for this kind of use case. This tutorial will show you how you can implement the use of non-English characters for your push notifications using built-in GameSparks features:

  • Configuring Push Notifications - provides links out to background information on how to set up push notifications.
  • The Segmentation Problem - identifies and explains the main issue that arises if you try to use segmentation for push notification messages which use non-English language characters.
  • How to Encode Push Notifications in Cloud Code - explains how to encode non-English language characters for use in push notifications and test them in the Test Harness.
  • Configuring Different Language Data Using Properties and Property Sets - explains how to use Properties and Property Sets to set up different language versions for your push notifications.
  • Improving the Solution - how to improve on the solution.

Configuring Push Notifications

In this tutorial, we won’t go into how to configure push notifications for your desired platform. We have plenty of documentation on how they are configured and we recommend that you work through these tutorials to have your setup working correctly before moving on to follow this tutorial:

The Segmentation Problem

GameSparks allows you to segment your configurable objects in your game based on custom segments. For example, you can segment your messages by language and have different translations per language for your GameSparks messages. This approach will work fine for sending GameSparks messages but an issue emerges when it comes to receiving the messages as push notifications. Non-English language characters first need to be encoded in UTF-8 before they are sent otherwise the text will display like this: ??????, instead of appearing as the proper, non-English language characters that you want in your message:


How to Encode Push Notifications in Cloud Code

For non-English characters, you must encode messages to Unicode Transformation Format (UTF-8).  You can do this using a simple JavaScript function that converts a string to UTF-8:

To use this function, we pass in a string and it will return the string as UTF-8 encoded. In our example below, we'll demonstrate how this done with Japanese language characters. The text we are going to send is こんにちは which means "hello" in Japanese.


To do this, we store the Japanese text inside a JSON object and set its values for the message title and body. For this example, we simply pass in the same text for both values and we are going to send the message to the player who is currently logged in. Then we encode our string using our UTF-8 function when setting the message data:


If you test this in the Test Harness, this is what the response will look like:

You will notice the text looks strange but don't worry, this is just the Test Harness not understanding the encoding. Your message will display the proper characters on your device. This is what the notification will look like on a phone:

Notice that we no longer have ????? but the actual Japanese characters we want! This is great, we've set up our push notification to display the text correctly on our mobile devices. However, we have a small issue with our Cloud Code. By default, the Cloud Code engine does not support Japanese or Arabic characters. If we refresh the page, it will convert our hard-coded Japanese characters into ?????. This is not what we want, but luckily there is a way around this limitation.  We'll store our translations as Properties to solve this problem.


Configuring Different Language Data Using Properties and Property Sets

Properties allow you to store your own custom JSON configurations inside the GameSpark portal. For our example, we are going to store each translation we need for our game inside a Property and then create a Property Set to group them together. For more detailed information on Properties and Property Sets, visit the following link to our documentation:

Creating the Language Properties

To create a Property go to Configurator > Properties > Properties then click Add to create a new Property. In the Properties panel, give your Property a Short Code, Name and Description. For this tutorial, we are going to have an individual Property for each translation. Inside the Code section for each message type, we are going to have a Title and Body for each type of push notification we want. We can add more later if needed but for now we are only going to have two attributes and keep the example simple:

 

In our example, we have created 3 Properties: one for Japanese, one for English, and one for Arabic. To create the other Properties do the same but use different values for the translations.

Creating the Property Set

When you created all your Properties, you can create a Property Set to hold all the properties together. For each language, add a key which will allow you to access the Property in Cloud Code that corresponds to each language.

Working with Properties in Cloud Code

Now that we have our Properties and Property Sets set up, we can now access them in our Cloud Code.


To access a Property Set, we can use:


Spark.getProperties().getPropertySet(“PropertySetName”);


Then, we can use dot notation to get the Property we need for given language:

Improving the Solution

This is all we need to get our push notifications working with Properties. However, we can make some improvements to the code, because currently our code only works for hard-coded Japanese Properties. It would be nice to pass in language and get the appropriate Property we need. In your push notification Event, you can add an Attribute called Language and set its Default Value to English and Default Aggregation Type to Used In Script:


We are going to check the language passed in and return the Property based on the language. We do this by creating a simple function that takes in a language and Property Set and, by using a switch statement, determines which property to return:

Now that we have created our function, we can apply this to our previous Cloud Code to filter the Properties we want to get back:

Conclusion

Push notifications are a powerful tool that game developers have at their disposal to help notify players on things going on in their game or for encouraging players to come back to their game. By localizing your push notifications, you are reaching and appealing to a larger player base and improving the user experience for all your players worldwide.