This chapter summarizes items that must be supported when handling the patch update-checking-sequence. Refer to this information when creating a patch.
9.2.1 Displaying the Patch Version
If the application has been patched, it must display the current patch version after startup, in a font large enough to be readable. For example, you might display the patch version on the title screen or a settings screen. Note, however, that patch version notation is not required if the patch only updates the e-manual.
If the base version is version 1.0.0, Nintendo recommends that the patch version increment these digits to reflect the extent of changes in the patch: for example, "version 2.0.0" for a patch that adds features, "version 1.1.0" for a patch containing bug revisions, and "version 1.0.1" for a patch containing very minor adjustments. Nintendo also recommends that your version notation stay consistent between patches and remasters. For example, if a remastered card-based application and a patched version of the same application contain the same revisions, Nintendo recommends giving them the same version number. Different version numbers could suggest that different revisions have been applied to each.
This information allows users themselves to check which patch has been applied and whether it was applied successfully. Having this version information also allows for more efficient user support.
If no patch has been applied to the application, either display nothing, or display its initial version.
9.2.1.1 Displaying the Patch Version
Guideline Item |
Applications must display the version of the currently applied patch on at least one screen (such as in the title screen or a settings screen). |
---|---|
Software to Be Tested |
Patched versions of applications. |
Exceptions |
If the update only affected the e-manual.
|
Test Method |
Check the location within the application (such as the title screen or settings screen) where the patch version is displayed.
|
Pass/Fail Determination |
Passes if the patch version is displayed. |
9.2.2 Checking Patch Updates and Notifying User if Patching Failed
If you anticipate patches and implement patch update checking in your unpatched base application, Nintendo recommends calling the nn::ec::IsPatchAppliedCorrectly function inside your application to check whether patches have been applied correctly. If they have not been applied correctly (the function returns ResultPatchNotAppliedCorrectly), Nintendo recommends prompting the user to go to System Settings ⇒ Data Management ⇒ Add-On Content Management and delete the patch.
A patch not being applied correctly means that the patch is corrupted in some way. In such cases, the system launches the application from the unpatched base application instead, so the patch is not correctly applied. If this is the case, the previous state can be recovered by deleting the patch. Therefore, notify and instruct the user to delete the patch if patching has failed. The error code returned as a ResultError can be displayed for this notification.
If this state is ignored and nn::ec::CheckAndInstallPatch is called, the same error is returned.
No required guideline items.
9.2.3 Getting Patch by Performing Shop Jump from Within the Application
If you use the nn::applet::CTR::JumpToEShopPatchPage function to jump to the patch download page in Nintendo eShop from within your application, you must implement and handle this feature as described below.
It is possible to perform this shop jump even from an application that is fully patched and up-to-date, but doing so is not a very good user experience, because the application closes in order to jump to Nintendo eShop and after all that the user finds out that there are no patches to apply. Therefore Nintendo recommends performing this shop jump either in response to an error or after checking the application's version. Cases where the authentication server returns error 002-0120, where the account server returns error 022-2512, or where your independent service detects that the client version is out-of-date would all be appropriate to handle this way.
If the remaster version is out-of-date and triggers either of the following errors, it is acceptable to transition directly to a shop jump without displaying the error.
- 002-0120 (authentication server)
- 022-2512 (account server)
Also note that the system is now able to periodically check for new patches and notify the user about them on the HOME Menu, and the user can start Nintendo eShop from the HOME Menu and get new patches that way. Thus there is no requirement to implement the kind of shop jump feature described above where your application calls the nn::applet::CTR::JumpToEShopPatchPage function in response to errors or after checking the application's version.
Saving Game Data Before Jumping
In order to jump to Nintendo eShop, you must first close the game. For that reason, you must always save game data before jumping. It is not necessary to save in cases where there is no data to save, such as when the user is on the title screen.
User Confirmation for a Shop Jump
Before calling the nn::applet::CTR::JumpToEShopPatchPage function, always notify the user that the application will jump to Nintendo eShop and obtain user consent (display Yes and No options allowing the user to accept or decline the jump). The following message is an example of the kind of message you must display.
This software must be updated before you can use network services.
Close the software now and go to Nintendo eShop?
Yes / No
9.2.3.1 Saving Game Data Before Jumping
Guideline Item |
The application must save its game data prior to jumping to Nintendo eShop.
|
---|---|
Software to Be Tested |
Applications that use the nn::applet::CTR::JumpToEShopPatchPage function. |
Exceptions |
Instances where there is no data to save. |
Test Method |
Perform a shop jump in order to download a patch. |
Pass/Fail Determination |
Passes if the application saves its game data prior to jumping. |
9.2.3.2 User Confirmation for a Shop Jump
Guideline Item |
Before calling the nn::applet::CTR::JumpToEShopPatchPage function, the application must notify the user that it will jump to Nintendo eShop, and obtain user consent. |
---|---|
Software to Be Tested |
Applications that use the nn::applet::CTR::JumpToEShopPatchPage function. |
Test Method |
Perform a shop jump in order to download a patch.
|
Pass/Fail Determination |
Passes if all of the following conditions are met.
|
9.2.4 Handling Patch Updates from Inside the Application
Prohibition Against Applying Patches from Within the Application
Features have been added to the system so that it now checks for new patches periodically and notifies the user about them on the HOME Menu. It is also now possible to jump to the patch download page on Nintendo eShop even from within the application by using the nn::applet::CTR::JumpToEShopPatchPage function. The patch update feature available previously, which used the nn::ec::CTR::CheckAndInstallPatch function, was burdensome both on application developers and on the server environment backend. Therefore, it is prohibited for new titles to apply patches from within the application via the nn::ec::CTR::CheckAndInstallPatch function. Cases of updates or localized versions of applications where support for this feature is grandfathered in and where you wish to continue using this function are treated as exceptions. If your application is one of these exceptions and you apply patches from within the application, you must implement the feature as described below.
The entire sequence of checking for patch updates through downloading the updates is performed by the EC applet, which also displays its progress. Therefore, when checking for patch updates the application is only required to support the following.
Saving of Game Data Before the Patch Update
The application must always save the game data before checking for updates and downloading a patch. After a patch is downloaded, the application must restart. For this reason, game data must be saved before checking for updates and downloading them. This does not apply if there is no data that needs to be saved, such as if the patch is only updating the title screen of an application.
User Confirmation for Patch Updates
Before checking for and downloading patch updates by calling the nn::ec::CheckAndInstallPatch function, always notify the user that the application will check for and download updates and obtain user consent (display Yes and No options allowing the user to accept or decline the update). Additionally, if users lose access to some services when a patch is released and do not regain access until they apply the patch, you must also inform the user of this. For example, this applies in cases where services are only available to systems with the latest patch applied.
Installing a patch update could result in disadvantage for some users; this is why consent must be obtained before applying the update.
The EC applet contains no mechanism to obtain consent when downloading patches, and no way to check whether the patch is the latest without downloading it. Also, the way patches are implemented on Nintendo 3DS does not provide a way to obtain the content of the update before doing the update, so this must be handled by the application.
Displaying Errors
If an error that must be displayed to the user occurs while checking for or downloading patches, the application must display the error code and error message.
See the ECDK API Function Reference Manual regarding errors that must be displayed and how to obtain error codes for the error/EULA applet.
If the remaster version is out-of-date and triggers the following errors, it is acceptable to transition directly to the patch update checking sequence without displaying the error.
- 002-0120 (authentication server)
- 022-2512 (account server)
Restarting after Patch Update
The system actually applies the patch at startup, so applications must restart after they receive a patch.
9.2.4.1 Saving Game Data
Guideline Item |
The application must save game data before checking for and downloading a patch. |
---|---|
Software to Be Tested |
Applications that check for and download patch updates via the EC applet. |
Exceptions |
If there is not any data that needs to be saved. |
Test Method |
Apply the patch to the application. |
Pass/Fail Determination |
Passes if game data is saved prior to checking for and downloading the patch. |
9.2.4.2 User Confirmation for Patch Updates
Guideline Item |
The application must notify the user that it will check for and download updates and must get user consent before checking for or downloading patches. If not applying the patch will render the user unable to use services that had been available until that point, they must be notified of this as well. |
---|---|
Software to Be Tested |
Applications that check for and download patch updates via the EC applet. |
Test Method |
Apply the patch to the application. |
Pass/Fail Determination |
|
9.2.4.3 Patches: Displaying Errors
Guideline Item |
If an error occurs while checking for or downloading a patch, the application must display the error code and message. |
---|---|
Software to Be Tested |
Applications that check for and download patch updates via the EC applet. |
Test Method |
|
Pass/Fail Determination |
Passes if the required error codes and messages are displayed in step 2 in every case. |
9.2.4.4 Prohibition Against Applying Patches from Within the Application
Guideline Item |
New titles must not use the nn::ec::CTR::CheckAndInstallPatch function to apply patches from within the application. |
---|---|
Software to Be Tested |
Applications that perform any patch-related operations. |
Exceptions |
Any of the following:
|
Test Method |
Perform a patch update or any other patch-related operation.
|
Pass/Fail Determination |
Passes if the patch update does not occur within the application. |
9.2.5 Ensuring Data Compatibility
Patched applications must be compatible with all previously-created save data (including extra data and data used with StreetPass and SpotPass).
Although it is not required for save data created by the patched application to be fully compatible with unpatched earlier versions of the application, avoid creating save data that would make it impossible to progress if loaded in the unpatched version. If you cannot avoid creating save data which makes it impossible to progress if loaded in an unpatched version, you must use at least one of the following methods to handle the situation:
- Display a message informing the user that deleting the patch will make data created by the application unusable. (For example, display this when applying the patch.)
-
Display a message informing the user that they must redownload the patch in order to progress in the game. (For example, display this when the user has deleted the patch and then loaded incompatible save data.)
On Nintendo 3DS systems, it is possible for users to revert their applications to earlier unpatched versions either by deleting the patch in System Settings or by changing the combination of the system + SD card (or Game Card + SD card) that they are using.
9.2.5.1 Supporting Forward Compatibility
Guideline Item |
Patched applications must be compatible with all previously-created data (including save data, extra data, and data used with StreetPass and SpotPass). |
---|---|
Software to Be Tested |
Patches |
Test Method |
|
Pass/Fail Determination |
Passes if, in step 3, the application can access and use all the kinds of data without problems. |
9.2.5.2 Supporting Backward Compatibility
Guideline Item |
Data created by patched applications (including save data, extra data, and data used with StreetPass and SpotPass) must not make it impossible to progress if used in unpatched, reverted versions of the application. |
---|---|
Software to Be Tested |
Patches
|
Exceptions |
Cases where the application uses any of the following methods to handle the situation:
|
Test Method |
|
Pass/Fail Determination |
Passes if it is possible to progress in the application in step 3. |
9.2.6 Restrictions When Updating Download Play Client Programs via Patches
Since the firmware-update data included in the main part of the application cannot be updated via a patch, it may not always be possible to update the system on the downloading side to the required firmware. Therefore, it is prohibited to use a patch to change the SDK version of a Download Play client program. This is similar to the handling also described in section 10.1.5 Restrictions When Updating Download Play Client Programs via Remastered Versions. Also note if you add a new client program in a patch, the SDK version of the Download Play client program must be the same SDK version that was used to build the original application. It is not an issue if the SDK version of the main application itself is updated, as long as the SDK version of the Download Play client program stays the same.
If your application contains multiple Download Play client programs, it is necessary to include all of them in your patch, even if the patch only updates one of them. This is because after application of a patch, only the Download Play client programs in the patch are accessed.
9.2.6.1 Checking the SDK When Using Patches to Update Applications that Contain Download Play Client Programs
Guideline Item |
When you use a patch to update a Download Play client program, the patch must not change the SDK version of the Download Play client program.
|
---|---|
Software to Be Tested |
Download Play client programs included in application patches. |
Test Method |
Check using Master Editor version 2.3 or later. |
Pass/Fail Determination |
Passes if the SDK version of the Download Play client program(s) is the same as the SDK version used prior to the application of the patch.
|
9.2.6.2 Checking the SDK When Using Patches to Add New Download Play Client Programs
Guideline Item |
When you use a patch to add a new Download Play client program, the new client program must use the same SDK version as the original application.
|
---|---|
Software to Be Tested |
Download Play client programs included in application patches. |
Test Method |
Check using Master Editor version 2.3 or later. |
Pass/Fail Determination |
Passes if the SDK version of the Download Play client program(s) is the same as the SDK version used by the original application.
|