First steps

To get started, you need to:

  • Sign up for UGS, including Analytics.
  • Link your dashboard project to a Unity Editor project.
  • Initialize UGS in your game code.

Sign up

To use Push Notifications, you need to sign up for Unity Analytics, which is part of Unity Gaming Services (UGS). For more information about Analytics pricing, see here. To learn more about Push Notifications fair usage visit here.

If you don't have a Unity account, create one and create a new project to sign up for Unity Gaming Services.

Important: Only Organization Owners can sign up for Analytics.

  1. Sign into the Unity Services Dashboard.
  2. Select Explore Services in the side panel.
  3. Select Sign Up in the top banner and follow the instructions.
  4. Review Analytics documentation

To use the Unity Push Notifications service, you’re required to link your project to a cloud project in the Unity Editor through a project ID. Follow these steps to get your project ID.

  1. In the Unity Editor menu, go to Edit -> Project Settings to open the Services tab.
  2. If you’re not already signed in with your Unity ID, either create a new Unity ID or sign in.
  3. If you want to create a new project, select your organization and select Create. If you want to link to an existing project, select I already have a Unity Project ID.
  4. Select your organization and project from the dropdown, and select Link.

You can find your project ID from the Settings tab in the Services window.

Integration

The Push Notifications SDK supports both iOS 10+ and Android SDK >= 26 (Oreo).

Summary of the integration steps:

  1. Integrate the SDK: Integrate package, register for Push Notifications, and enter settings/keys.
  2. Upload keys: Locate and upload private keys (Firebase & Apple) to the Unity Dashboard.
  3. Test integration: Send a test notification to your device to ensure integration is correct.
  4. Create notification campaign: Create and schedule your first notification on the Unity Dashboard.

1. Integrate the Push Notifications SDK

Install the Push Notifications SDK

The Push Notifications SDK might not be visible by default inside the Package Manager in your Unity Editor version.

You can install the Push Notifications SDK inside your Unity Project in one of three ways:

1. Import using the Unity Registry
  1. Open your Project Settings from Edit -> Project Settings.
  2. Enable pre-release packages from Package Manager -> Advanced Settings -> Enable Pre-release Packages.
  3. Open the package manager from Component -> Package Manager.
  4. Under the Packages dropdown, select Unity Registry.
  5. Search for Push Notifications in the search bar in the top right to view the Push Notifications package.
  6. Select Install in the top right.
2. Import by name
  1. Open the package manager through Component -> Package Manager.
  2. Select the Add (+) button in the top left to add a new package and select Add package by name.
  3. Type in com.unity.services.push-notifications as the Git URL and add.
3. Import using the "manifest.json" file
  1. Copy the following code snippet and adjust the package version:

    "com.unity.services.push-notifications": "4.0.0-pre.1"
  2. Go to the root of your project folder in the file explorer, then go to the package folder Packages/manifest.json.

  3. Add the copied code at the end of the manifest.json file and append a , at the end if needed.

Register for Push Notifications

To receive Push Notifications, your app needs to register for Push Notifications. Follow Registering for Push Notifications for details.

2. Upload your service keys

To send notifications from the Unity Gaming Services dashboard, you need to upload service keys from Firebase for Android and from your Apple Developer account for iOS.

Google

You need a Firebase Service Account Key to be added to your Unity project settings before sending notifications to Android devices. This needs to be done for every UGS environment of the game that you expect to test or use notifications with.

  1. Go to your Firebase Console and select your project.
  2. Go to Project Settings and select Service accounts at the top.
  3. Select Create service account.
  4. Select Generate new private key.
  5. Select Generate key to download the key file.
  6. In the Unity Cloud Dashboard, select Products > Push Notifications > Settings then go to Google Keys and select the Add Key or Edit Icon in the "Google Key" row.
  7. You will be asked to return to the Editor to complete the Configure the SDK step.
  8. In the Editor navigate to Project Settings > Services > Push Notifications and configure your Android (Firebase) Settings.
    Then return to the Dashboard and click the Next button to move to the next step in the Google Key configuration wizard.
  9. Upload the private key created in the previous steps and select Finish.

For security reasons this file won’t be visible if you re-enter the edit settings page.

Apple

You need to add an Apple key, project, and account details to your Unity project settings before sending notifications to Apple devices. You can reuse the same Apple key between games, environments, and development and production builds in the Unity Dashboard (go to step 8 if you already have one). This needs to be done for every UGS environment of the game that you expect to test or use notifications with.

  1. Log in to your Apple Developer console.

  2. Go to the Certificates, Identifiers & Profiles page and select Keys.

  3. Select + to create a new key.

  4. Name your key and enable the “Apple Push Notifications service (APNs)” option to enable notifications, then select Continue. Note, you can only enable this capability on two keys per account.

  5. Select Register on the next page to confirm.

  6. Download the generated key and make note of the Key ID provided as you’ll need it later. You can only download the key file once; it needs to be revoked and regenerated if lost.

  7. Go to Player Engagement > Notifications > Settings for your project in the Unity Dashboard, click the Set Up Keys link in the Setup banner at the top, then select Add Key or the Edit Icon in the "Apple Key" row.

  8. There are five fields that need to be populated:

  • Key: Upload the key created in the previous steps.
  • Key ID: This is provided when you registered the key and can also be retrieved by selecting the key in the Apple Developer console.
  • Team ID: This is your team ID displayed under your account name on the Apple Developer console.
  • Topic ID: Populate with the bundle identifier for your game. It needs to exactly match the one in “Identifiers” in the “Certificates, Identifiers & Profiles” page in your Apple Developer console.
  • Sandbox: If you want to message players from a development/debug build of your game, set the sandbox value to True. If you want to message users on a production build, set to False.
  1. Select Finish. For security reasons this file won’t be visible if you re-enter the edit settings page.

  2. The "Mobile Notifications" package has been imported into your project as a dependency of "Push Notifications". In the Editor navigate to Project Settings > Mobile Notifications and select the iOS section. Make sure Request Authorization, Enable Push Notifications and Register for Push Notifications on App Launch options are checked.
    Refer to the Mobile Notifications documentation for more information on configuration and the additional features offered by this package.

  3. When building the application within XCODE, ensure that the app is given the “Remote Notification” capabilities so it can receive notifications.

    You’ll receive the following error message at runtime if you fail to do this:
    Failed to register for remote notifications: no valid “aps-environment” entitlement string found for application

3. Test your integration

Test your Push Notification integration within your app by following the testing guide.

If you encounter any issues whilst testing, follow the troubleshooting guide for debugging common issues.

4. Create a notification campaign

You can now create your first notification campaign to start using Push Notifications.