BundleDisplayName

BundleDisplayName

#Overview

name: BundleDisplayName

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 3 C++ source files. Also referenced in 4 C# build files meaning it may affect the build system logic.

#Summary

#Usage in the C++ source code

The purpose of BundleDisplayName is to specify the display name for the iOS application. This name will be shown under the app icon on the device.

BundleDisplayName is primarily used in the iOS platform-specific settings and customization of Unreal Engine. It’s part of the IOSRuntimeSettings module, which is responsible for managing iOS-specific configuration options.

The value of this variable is set in multiple places:

  1. It has a default value of “UnrealGame” in the UIOSRuntimeSettings constructor (IOSRuntimeSettings.cpp).
  2. It can be modified through the Unreal Engine editor interface, as it’s exposed as an editable property in the IOSRuntimeSettings class (IOSRuntimeSettings.h).

BundleDisplayName interacts with other iOS-specific variables such as BundleName and BundleIdentifier. These variables collectively define the app’s identity and how it appears on iOS devices.

Developers must be aware that:

  1. This variable directly affects how the app is presented to users on their iOS devices.
  2. It should be set to a user-friendly, readable name that accurately represents the app.
  3. Changes to this variable will require rebuilding and redeploying the app to see the effects.

Best practices when using this variable include:

  1. Choose a clear, concise name that reflects the app’s purpose or brand.
  2. Ensure the name is appropriate for your target audience and market.
  3. Consider localization requirements if your app will be available in multiple languages.
  4. Keep it consistent with your app’s marketing materials and other platforms if it’s a multi-platform app.
  5. Avoid using special characters or overly long names that might get truncated on device screens.

#Usage in the C# source code and build system

The purpose of BundleDisplayName is to set the display name of the app bundle for iOS and tvOS platforms. This variable is used to define a longer, more descriptive name for the app that appears on the device’s home screen, which can be different from the shorter bundle name.

This setting variable is primarily relied upon by the iOS and tvOS subsystems of Unreal Engine. Specifically, it is used in the build and deployment processes for these platforms, as evidenced by its references in UEBuildIOS.cs, UEDeployIOS.cs, and UEDeployTVOS.cs files.

The value of this variable is set in the project’s configuration file, specifically in the “/Script/UnrealEd.ProjectPackagingSettings” section for iOS, and “/Script/IOSRuntimeSettings.IOSRuntimeSettings” section for both iOS and tvOS.

BundleDisplayName interacts with other variables related to app packaging and identification, such as BundleIdentifier and BundleShortVersion. These variables collectively define the app’s identity and version information on iOS and tvOS platforms.

Developers must be aware that the BundleDisplayName is crucial for proper identification of the app on the user’s device. It should be descriptive enough to distinguish the app from others but concise enough to fit within the iOS/tvOS UI constraints.

Best practices when using this variable include:

  1. Ensuring the display name is clear, concise, and representative of the app’s function.
  2. Keeping it consistent with the app’s branding and marketing materials.
  3. Considering localization if the app is intended for multiple language markets.
  4. Avoiding special characters that might cause issues in different locales.
  5. Testing the display name on various device models to ensure proper rendering.

The associated variable BundleIdentifier is equally important in the app packaging process. The purpose of BundleIdentifier is to provide a unique identifier for the app in the iOS/tvOS ecosystem. It is typically in a reverse domain name format (e.g., com.companyname.appname).

BundleIdentifier is used by the same iOS and tvOS subsystems as BundleDisplayName. It’s referenced in the UEDeployIOS.cs and UEDeployTVOS.cs files, indicating its importance in the deployment process.

The value of BundleIdentifier is also set in the “/Script/IOSRuntimeSettings.IOSRuntimeSettings” section of the project’s configuration file.

This variable interacts closely with BundleDisplayName and other app identification variables. It’s crucial for app store submissions, push notifications, and other platform-specific features.

Developers must ensure that the BundleIdentifier is unique for each app they publish. It should remain consistent across updates to maintain continuity in areas like user data and push notifications.

Best practices for BundleIdentifier include:

  1. Using a reverse domain name style (e.g., com.companyname.appname) to ensure uniqueness.
  2. Keeping it lowercase and using only alphanumeric characters, hyphens, and periods.
  3. Ensuring it matches the bundle ID used in the Apple Developer portal and App Store Connect.
  4. Avoiding changes to the bundle identifier after the app has been released, as this can cause issues with updates and user data.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:2997, section: [/Script/IOSRuntimeSettings.IOSRuntimeSettings]

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Developer/IOS/IOSPlatformEditor/Private/IOSTargetSettingsCustomization.cpp:796

Scope: file

Source code excerpt:

	FSimpleDelegate OnEnableMetalMRT = FSimpleDelegate::CreateSP(this, &FIOSTargetSettingsCustomization::UpdateMetalMRTWarning);

	SETUP_PLIST_PROP(BundleDisplayName, BundleCategory);
	SETUP_PLIST_PROP(BundleName, BundleCategory);
	SETUP_STATUS_PROP(BundleIdentifier, BundleCategory);
	SETUP_PLIST_PROP(VersionInfo, BundleCategory);
	SETUP_PLIST_PROP(bSupportsPortraitOrientation, OrientationCategory);
	SETUP_PLIST_PROP(bSupportsUpsideDownOrientation, OrientationCategory);
	SETUP_PLIST_PROP(bSupportsLandscapeLeftOrientation, OrientationCategory);

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Classes/IOSRuntimeSettings.h:392

Scope (from outer to inner):

file
class        class UIOSRuntimeSettings : public UObject

Source code excerpt:

	// Specifies the the display name for the application. This will be displayed under the icon on the device.
	UPROPERTY(GlobalConfig, EditAnywhere, Category = BundleInformation)
	FString BundleDisplayName;

	// Specifies the the name of the application bundle. This is the short name for the application bundle.
	UPROPERTY(GlobalConfig, EditAnywhere, Category = BundleInformation)
	FString BundleName;

	// Specifies the bundle identifier for the application.

#Loc: <Workspace>/Engine/Source/Runtime/IOS/IOSRuntimeSettings/Private/IOSRuntimeSettings.cpp:31

Scope (from outer to inner):

file
function     UIOSRuntimeSettings::UIOSRuntimeSettings

Source code excerpt:

	bSupportsITunesFileSharing = false;
	bSupportsFilesApp = false;
	BundleDisplayName = TEXT("UnrealGame");
	BundleName = TEXT("MyUnrealGame");
	BundleIdentifier = TEXT("com.YourCompany.GameNameNoSpaces");
	VersionInfo = TEXT("1.0.0");
    FrameRateLock = EPowerUsageFrameRateLock::PUFRL_30;
	bEnableDynamicMaxFPS = false;
	bSupportsIPad = true;

#References in C# build files

This variable is referenced in the following C# build files:

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/UEBuildIOS.cs:350

		/// longer display name than BundleName if needed
		/// </summary>
		[ConfigFile(ConfigHierarchyType.Game, "/Script/UnrealEd.ProjectPackagingSettings", "BundleDisplayName")]
		public readonly string BundleDisplayName = "";

		/// <summary>
		/// Which version of the iOS to allow at run time
		/// </summary>
		public virtual string RuntimeVersion

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/UEDeployIOS.cs:607

			// bundle display name
			string BundleDisplayName;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "BundleDisplayName", out BundleDisplayName);

			// bundle identifier
			string BundleIdentifier;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "BundleIdentifier", out BundleIdentifier);
			if (!String.IsNullOrEmpty(BundleID))
			{

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/UEDeployIOS.cs:278

			// bundle display name
			string BundleDisplayName;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "BundleDisplayName", out BundleDisplayName);

			// short version string
			string BundleShortVersion;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "VersionInfo", out BundleShortVersion);

			// Get Google Support details

Location: <Workspace>/Engine/Source/Programs/UnrealBuildTool/Platform/TVOS/UEDeployTVOS.cs:47

			// bundle display name
			string BundleDisplayName;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "BundleDisplayName", out BundleDisplayName);

			// bundle identifier
			string BundleIdentifier;
			Ini.GetString("/Script/IOSRuntimeSettings.IOSRuntimeSettings", "BundleIdentifier", out BundleIdentifier);
			if (!String.IsNullOrEmpty(BundleID))
			{