Another Tour of macOS Tours (touristd)

In a previous post, I stumbled on the config file that contains all of Apple’s “New to Mac” tours. For me and my efforts to give organizations the ability to suppress these prompts this was an extremely helpful discovery, removing much of the previous confusion and tedious checks to determine what, if anything, had changed. After the recent announcement of a new graphics model with the 16 in. MacBook Pro, I decided to use the opportunity to revisit exactly how Apple is updating this config file and look more closely at the actual configuration of the file itself.

You can find this most recent addition committed in the macos-touristd-config repo.

For one, the config file has a version. The original commit in the macos-touristd-config repo listed a version of 0.15 with the most recent being 0.16. So, it’s likely safe to say that every change is incremented 0.01 for a total of now 16 changes since its implementation.

Secondly, new hardware additions are appended to the top of the file (but not all new additions). Conceivably the oldest would be at the bottom. Hardware tours are identified as having a type of 2.

While new hardware appears to be added to the top, not all additions are added this way. For example, all of the “Mac Basics” tours are listed at the bottom of the file, identified with a type value of 0. For whatever reason, the “What’s New on Mac” tours – identified with a type of 1 – follow the same organization as the hardware tours, with the “What’s New with Catalina” appearing above previous OSs and models.

At the very bottom of the file just above the version of the config itself, Apple appears to define the “New to Mac” notification settings and behavior. By default, the initial prompt appears approximately 4 hours (minHoursNotificationDelay) after initial setup / login and provides only Show / Later button options. The next prompt appears after 24 hours, this time displaying Show and a dropdown of additional Later options, including those to never be shown again.

Within each tour dictionary, there is a set range of keys and values. These keys are listed below in order of appearance:

  • waxwing
  • boards
  • iconAsset
  • id
  • platform
  • minimumScale
  • osVersion
  • fromOsVersion (only “What’s New” tours)
  • type
  • url

Referring to the most recent addition above, boards refers the actual board IDs of the Mac model listed. Mr. Macintosh has a full list of all Mac board IDs, if you’re interested. This would appear is the primary differentiator between what tour is assigned to what Mac. The majority of tours are only applicable for 1 board ID, but there are several that include 2, 3, or even 4 of these.

Interestingly, with the most recently addition of the new graphics 16 in. MacBook Pro model, it appears Apple actually did not create a new unique tour despite adding a dictionary for the new board ID. It uses largely the same configuration as the previous late 2019 MacBook Pro with the only difference being the osVersion. Why then did Apple not simply add the new board ID to existing late 2019 tour? Your guess is as good as mine, but I don’t see any reason why Apple needed to do it this way.

All tour dictionaries have a waxwing key value of true except for two: High Sierra “What’s New” and High Sierra “Basics”. Why these and not others, I have yet to determine.

iconAsset is what defines the location of the tour icon. This ensures the hardware-specific icon for the tour is displayed in the Alert-style notification. These applicable icons are subsequently stored in ~/Library/Application Support/com.apple.touristd.

id is what uniquely identifies the tour within the com.apple.touristd.plist file. Previously, Apple used a series of what appear to be random characters to identify these (ex. lQlm1yrMS0GPVyAL44id+A) but as of recently have opted for more human-readable ids (ex. catalina_late-2019_macbook-pro). When a tour is marked as ‘viewed’, this id is what’s used in the key name, and is what is used by ProfileCreator and iMazing Profile Editor to suppress these prompts.

seed-viewed-lQlm1yrMS0GPVyAL44id+A = 2019-12-20 05:35:08 +0000

platform is what defines the device type. This appears to only have a value of mac, so not a terribly useful key given that to my knowledge touristd is not implemented on iOS or tvOS, or at least in the same way.

osVersion is an array of regular expressions which limit the scope of the tour to matching OS versions. So, if the board ID matches but the OS regex does not, no tour is displayed. Within a given hardware tour, the value of of osVersion is typically limited to one major OS. In some cases though there are multiple, like with the mid 2017 27in. iMac.

Why 10.12 and 10.14, but not 10.13?

Given Apple’s annual major OS release cycle, the highest we’ve seen the minor version reach is .6, but conceivably this could go higher. Why then does Apple indicate a second number range for the minor version? Assuming Apple were to add an additional number, given the latest available version of Catalina – 10.15.5 – a regex of 10\.15\.[5-9]* would achieve a the same successful match as the used 10\.15\.[5-9][5-9]* regex. However, with the used regex the lowest possible macOS version that would achieve a match is 10.15.55. Why include the second number range at all if it’s not going to follow a logical numeric sequence, like 10.15.51?? And then why match any character after this with ‘*‘ ??? Another good question for Apple developers …

As previously mentioned, type refers to whether the tour is a “Mac Basics” – 0 -, “What’s New with Mac” – 1 -, or a hardware tour – 2.

I have yet to determine the purpose of minimumScale, as all dictionaries have a value of 1.

The only other key that is unique to the “What’s New” tours is the fromOsVersion key. This defines the minimum macOS version – which starts with OS 10 – with osVersion defining the maximum.

If you found this exploration interesting, please give it a like!

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s