Total Game Startup Instructions

TGS is a Unity plugin giving a simple set of customizable dialogs for users to interact with at your game’s first start-up.

Create a flow of start-up dialogs to deal with Language selection, Terms & Conditions, Privacy Policy, Personalized Ad Tracking (including IOS): then initialize your Analytics and Monetization SDKS.

Results are saved on the first game run, and resupplied to your code on subsequent runs.

Little code needed – alter the dialogs in the editor.

This document can be downloaded as a PDF file here:

Total Game Start InstructionsDownload

Add TGS to your project

Dependencies

Prerequisite Unity packages for TGS:

  • Unity Localization (required, even for one language) > https://docs.unity3d.com/Packages/com.unity.localization@1.1/manual/Installation.html
  • TextMeshPro (required)
  • Unity UI (required) should be installed already
  • IOS 14 Advertising Support (if building for IOS)

These should be installed before TGS.

Overview

TGS should be the first thing that runs when your game starts, before analytics and advertising are initialized, so the user can:

  1. Select a language (if needed for Unity localization)
  2. Read Terms and Conditions, Privacy Policy and accept (or deny) them.
  3. Accept/Deny your request for the Advertising ID used for your monetization SDK.
  4. (IOS 14+) Launch IOS system dialog to unlock Advertising ID for this App.
  5. Any other dialogs you wish to add.

* EU, California and others require a user to be able select their permission for tracking and personal information, whether it’s used for Analytics or Advertising. With TGS we assume it’s better to ask for permission before using anybody’s data, wherever they live.

TGS requires a single prefab added to the scene, which launches the dialogs you select in its properties. It comes with a set of commonly used dialogs, so you may only need to alter the text and links to fit your situation.

All text MUST be altered in the Unity Localization tables even if you only use one language

Window > Asset Management > Localization Tables > Edit Table Collection > TOTAL_GAME_STARTUP(String Table)

Do not alter text on the prefabs directly as they will not show correctly.

Quick Install

  1. Add the package as outlined above.
  2. Copy the whole folder Assets/Zzodo/TotalGameStartup/Example somewhere else in your project (so changes do not get overwritten if TGS is updated)
  3. Add TGS_Example_Scene.unity scene to your build list File > Build Settings > Scenes in Buildand move it to the top (or whatever suits your scene setup) and open the scene.
  4. SceneController can be edited and replaced with your own code, or use your own existing scripts. It starts the dialog process on the Canvas/TotalGameStartup object and receives the results of the dialogs via AllDialogsComplete event.
  5. Run the program. You will see the default dialogs with dummy text which should be replaced. Of the default dialogs, the first two “Terms and Condition” and “Privacy Policy” share a menu from which they are launched.
  6. Of the Advertising ID dialogs, one runs on IOS14+ only, and the other runs on all other operating systems (including IOS13.7 and below). NSUserTrackingUsageDescription and the native tracking dialog only exist on IOS14+)
  7. To replace the text:
    1. Go to Window > Asset Management > Localization Tables > Edit Table Collection > TOTAL_GAME_STARTUP(String Table)
    2. Find the key for “Privacy Policy” and “Terms and Conditions” and replace each cell with your own text for each necessary language.
  8. Open SceneController.cs script on the SceneControllergame object.
  9. Find the EndOfDialogs()method and react to the results given:Start Analytics
  10. Start Advertising SDK, etc.
  11. Pass variables if necessary (personalized ads).
  12. Add code to launch your own initial game scene (menu/intro, etc)
  13. All settings are auto saved by TGS in PlayerPrefs – so you don’t need to do it.
  14. If all “Critical” dialogs have been responded to by the user on the first run, no dialogs will be seen on the second run. AllDialogsComplete() will execute in both runs with results (either direct from user or saved).
  15. Language is automatically saved and passed to Unity localization on first and subsequent dialog runs, so no need to manually change the language in your code.

More Information

Basic Structure

  • Manager component has events sending information back to your code, and triggers the dialog process.
  • Flows contain multiple Dialogs or other sub-Flows.
  • Manager has a single “root” flow that triggers all other dialogs.
  • Flows can show items one-by-one or as a menu.
  • Flows (as a menu) and dialogs can be styled with a Dialog Style.
  • Flows can force their style on children.
  • Styles contain multiple settings for background & button images & colour
  • All are defined by scriptable objects
  • Text is all edited in Unity Localization

Item Creation

Dialogs, Flows, Styles are altered via scriptable objects and the Unity localization tables. You can use the existing ones, or create your own.

To create a new dialog: Create/TotalGameStartup/Dialogs/TGS_Dialog_Standard

To create a new flow: Create/TotalGameStartup/TGS_Flow

To create a new style: Create/TotalGameStartup/TGS_DialogStyle

Manager

TGS_MANAGER component. Manages the events returned to your code, triggers the dialog process via StartDialogs() method. Contains a single root flow.

The manager should always be the child of a canvas (preferably scaled to screen size) so it can display dialogs correctly.

Flows

Dialogs are show in Flows. Flows contain multiple dialogs that can be shown as a

  • Menu
  • One by one.

Flows can also contain other flows to segment different topics (e.g., Terms & Conditions vs Advertising).

In the example there is a “Root flow” that contains a “Terms flow” (terms and privacy policy shown as a menu) then a “Advertising flow” (shows a user tracking toggle on all platforms except IOS14, which shows a dialog, then IOS native tracking dialog.

Flows and dialogs  can be turned on and off on different platforms. (See the “Show only on” and “Hide only on” settings)

Both dialogs and flows can be marked as Critical. This means if the user didn’t complete the dialog on the first run, all dialogs will be shown again on subsequent runs. This could happen if the user quit the app before completion.

Dialog types

Currently there are 3 types of dialogs.

  • Language Selection (TGS_LanguageDialog)
  • A standard accept/deny dialog, with text (TGS_DialogDescription). It can show a toggle rather than buttons, or just an accept button

Apple IOS14 tracking dialog (TGS_IOSTrackingDialog). The same as above, but triggers IOS14 native tracking dialog on Accept/Close. NOTE: This dialog will always only show once unless user reinstalls app. It checks to see if the native tracking consent dialog can be shown before it displays. IOS14 only allows this once. User has to go to settings menu to turn tracking on/off after this.

Text and localization

All text is modified from the localization tables in the addressables menu. Window > Asset Management > Localization Tables > Edit Table Collection > TOTAL_GAME_STARTUP(String Table)

The scriptable objects representing Flows and Dialogs each have properties for Title text, body text, etc depending on the dialog.

Either edit the matching entry in the table to change the text, or create a new entry and select it in the appropriate dialog property. Don’t change the text in the internal prefabs, as the localization will not work.

Languages automatically appear on the language select screen if they are present in the project settings.

Common procedures

Here are how to do some common changes. These all assume you are using the default example supplied in the asset.

Remove all other languages

  1. Go to Edit > Project Settings > Localization
  2. Remove the unused languages from available locales.
  3.  Go to Example/Flows and select Root Flow
  4. In properties dialog, remove Language Selection from the list.

Stop dialogs showing at every start-up

This is by design so you can test. To change the behaviour:

  1. Click on your GameObject containing TotalGameStartup. (Canvas>TotalGameStartup in example scene)
  2. In the properties box find checkbox “Force show every time” and untick.

Change the order of dialogs or remove unwanted dialogs

  1. Click on your GameObject containing TotalGameStartup. (Canvas>TotalGameStartup in example scene)
  2. In the properties box find the default flow “RootFlow” and double click it.
  3. Inside the Root flow is an array with Language Selection, Terms and Conditions sub flow, Advertising sub flow.

  4. Drag the dialogs into a different order in the array to rearrange, or click the sub flows to alter their dialogs in the same way.

Note: We recommend the language selection is always shown first – all following dialogs are in the selected language.

Show all dialogs one by one, without a menu

  1. Click on your GameObject containing TotalGameStartup. (Canvas>TotalGameStartup in example scene)
  2. In the properties box find the “Root flow” and click the object.
  3. Inside the Root flow is an array with Language Selection, Terms and Conditions sub flow, Advertising sub flow.
  4. “Terms and conditions” flow is represented by a menu. Double click TermsAndConditionsFlow, and uncheck “show as menu”
  5. Dialogs will now show one by one with no menu.

Add a new dialog

  1. Create a new standard dialog.

  2. Give name and tag (name should be unique). They are not seen by the user.
  3. Go to Window > Asset Management > Localization Tables > Edit Table Collection > TOTAL_GAME_STARTUP(String Table)
  4. Add a new entry for the text and title you wish to use in the appropriate languages.
  5. Select the new keys in the new scriptable object.
  6. Add the new dialog to an existing flow (or create a new flow and insert that instead)

Change the style of dialogs

  1. By default, all dialogs use the same style forced down from the root flow.
  2. Click on your GameObject containing TotalGameStartup. (Canvas>TotalGameStartup in example scene)
  3. In the properties box find “Appearance” and select a new style.
  4. To let each dialog use its own style, uncheck “Force appearance on children” on any parent flows.

Create a new style

  1. Create a new style with CreateàTotalGameStartupàTGS_DialogStyle
  2. Create new image settings as necessary for background and buttons: CreateàTotalGameStartupàTGS_ImageSetting

  3. Set the background image, color etc, for the background or button

  4. Drag the image settings into the appropriate slot in the style
  5. Change the style for the dialog as in the last section

Change dialog text

  1. For existing dialogs in the examples, find its description. In the example they are in Assets\ZZodo\TotalGameStartup\Example\Dialogs
  2. Click the dialog and check the properties box.
  3. Look for the local text entry .
  4. Expand the entry and click the little button to the right. It will open the Localization dialog.

  5. Find matching entry and change the text for each language you use in your game.
  6. Alternatively, create a new text entry and change the entry local text refers to.
  7. This method allows multiple languages easily. Title and other text follows the same convention

Change the font used by dialogs

All dialogs use the same font for a specific language. Any GameObject using the TotalGameStartup script should also have a LanguageManager component attached.

  1. Click on your GameObject containing TotalGameStartup. (Canvas>TotalGameStartup in example scene)
  2. In the component list find LanguageManager component.
  3. Find the language you wish to change the font for.
  4. Select a new font from your assets.
  5. Create a new entry in the array first if you have created a new language not in the list

Font assets and materials should be created by the standard TextMeshPro procedures. If using a non-Latin font, it may be necessary to use a dynamic font instead. Please see the TextMeshPro documentation. https://docs.unity3d.com/Packages/com.unity.textmeshpro@3.0/manual/index.html

Advertising ID Settings

Apple IOS 14

  1. Navigate to Assets\ZZodo\TotalGameStartup\Settings\TGS_IOSTrackingSettings
  2. Set the text you want to appear when the IOS native tracking dialog is shown
  3. Check the box to add NSUserTrackingUsageDescription with the text above to info.plist on build.

When an IOS Tracking dialog is shown to the user, the native IOS user tracking dialog is shown to the user on IOS14. This will only happen once after an app is installed.  The above setting allows this feature and unlocks the advertising ID for your Ads SDK.

Android 12

  1. Navigate to Assets\ZZodo\TotalGameStartup\Settings\TGS_AndroidTrackingSettings
  2. Check the box to add com.google.android.gms.permission.AD_ID to the build manifest.

Android 12 and above require this setting to get the Advertising ID when the app is run. Otherwise, your Ads SDK will receive all zeros in the tracking ID and no personalized ads. This setting is not necessary on the latest versions of Admob, as it adds it automatically.

Others

Android 11 and below, IOS13 and below will give the advertising ID without specific user permission, so in these cases just use a simple dialog to request user permission for tracking. This is to adhere to GDPR, CCPA, etc.