Localizing Push Notifications to Use Non-English Characters
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 - Looks at how you might 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 other 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:
- How to configure Google Firebase Cloud Messaging Service
- How to configure iOS push notifications
- How to configure Windows Phone Push Notifications
The Segmentation Problem
GameSparks allows you to segment the 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 game's messages. This approach works for sending 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
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 is done for 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. We then 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'll notice the text looks strange but don't worry, this is simply 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, there's an 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! Fortunately, 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 GameSparks service. For our example, we're 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, follow this link:
Creating Language Properties
To create a Property:
1. Go to Configurator > Properties and select the Properties tab.
2. Click Add to create a new Property.
3. In the Properties panel, give your Property a Short Code, Name and Description.
For this tutorial, we're going to have an individual Property for each translation. Inside the Code section for each message type, we're 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're only going to have two attributes and keep the example simple:
For our example, we'll create 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've 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 access them in our Cloud Code. To access a Property Set, we can use:
Then, we can use dot notation to get the Property we need for a 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 a 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're 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've created our function, we can apply this to our previous Cloud Code to filter the Properties we want to get back:
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.