Enhanced suggestions for your journaling app

Hello! My name is Rene, I'm part of the Sensing And Connectivity team. I'm going to take you through the updated Journaling Suggestions API shipping with iOS 18. The Journaling Suggestions API helps people reflect on their lives. The practice of keeping a journal has a rich history, and taking a moment to reflect and write has even been shown to improve wellbeing and mental health. But sometimes, it can be difficult to know where to start, and that's where Journaling Suggestions can help: iOS can sense meaningful events in users' life and propose a starting point for their Journal entries. The suggestions are made of photos someone took, workouts, places they went to, and more.

And in just a few months, this API had tens of remarkable adoptions already, here showing a few of them! With iOS 18 additions, we are making this API even richer. This is what I am going to show you in this talk. But if you're just getting started with Journaling Suggestions, or simply need a more complete refresher, please refer to our tech talk from last year titled "Discover the Journaling Suggestions API" This will tell you everything you need to get started with the API, from how it is architected to how to leverage the different types of suggestions and assets the API delivers to your app, through the privacy considerations and user controls we built underneath the API. Starting with full Landscape support for those of you who propose this type of experience.

We will then continue with suggestion updates, covering new and updated asset types. Then we will dive into some best practices and learnings looking back at how the first adopters of the API used it. But let's start with Landscape support! In iOS 17.2, the Journaling Suggestions picker was locked in Portrait mode, but starting in iOS 18, it will follow your app orientation setting if your App supports landscape.

The interstitial screen, where users review the content they are about to share with your app, even takes full advantage of the wider space to show assets in larger size. Note that there is nothing for you to do to take advantage of this, if your application supports landscape orientation, the picker will just follow what your app is doing.

Now, let's dive into the suggestion updates that iOS 18 brings.

Journaling suggestions comes with many asset types to make journal entries beautiful and meaningful. In this talk, we will dive deeper into four of those assets types. State of Mind is a Health feature introduced last year, and your app can now receive an asset type for it as part of their suggestions. For those who are being active, but don't have an Apple Watch, the Motion Activity suggestions now support new types of activities.

Our Generic Media suggestions allow users to journal about the music and podcast they listen to within non-Apple applications. And finally, I will introduce reflection prompts, a type of suggestion that was initially only available to Journal, but is now available to you.

Let's start with State of Mind integration.

In iOS 17, we introduced a way for people to log their State of Mind in the Health app. Various studies have shown that writing about emotions, especially expressive writing, can lead to improvements in mental and physical health. Confronting upsetting experiences and emotions through writing, could help reduce negative effects, while savoring positive emotions could help heighten those feelings. And so State of Mind, had to be part of the journaling suggestions experience! There are two main categories of State of Mind samples that can be logged: Momentary emotions are describing how you feel in a given moment; Daily moods are describing how you've felt overall that day. In addition, each State of Mind sample comes with information that helps provide content about it: - The Valence provides information on how positive or negative the state of mind is.

- The Labels can describe what this state of mind was like for a user, for instance, they could report they were calm, peaceful, satisfied and others. - And finally, the Associations can help describe what contributed to generate the feeling, examples could be family, work, fitness and others.

Of course, all state of minds are good to journal about, no matter the valence, its kind or the associations that the user attaches to them. There's a lot more to discover about State of Mind as a feature and related updates coming in iOS 18. You should refer to the "Explore wellbeing APIs in HealthKit" talk to learn more about it, including how your app can log state of mind samples! For now, let's look into how State of Mind integrates with Journaling Suggestions. State of Mind suggestions can come as either a standalone suggestions or be bundled to an existing suggestion such as an outing, activity, or time at home. Users who started using Journaling Suggestions before iOS 18 will get a tip on their suggestion sheet to help them enable the State of Mind content. And for new users, this can be enabled during onboarding. And so, for journaling applications developers, this new content will just come as a new asset type when the user chooses to send it to your application.

Just like the other types of assets, the State of Mind comes with its own asset type called JournalingSuggestion.StateOfMind. The asset comes with a HKStateOfMind sample representation, including Valence, Labels and Associations. But also including an image url, and an associated light and dark color as well as a timestamp.

In order to add State of Mind assets content, you first retrieve all the content of type JournalingSuggestion.StateOfMind in a suggestion.

Then you can simply convert the asset in an AsyncImage using the item icon.

And for this example, we will also add an emoji representation of the asset via a custom function.

The get Emotion Emoji function could be very simple here, checking if the valence is positive, if it's negative, or if it's just somewhere in between.

Of course, you may use all of the State of Mind properties for your own application! Let's check out the result for this example In this case, the picked suggestion carries State of Mind content of a logged Daily Mood. Additionally, you could use the included labels and associations element values to create an expressive emotions journaling writing experience. And that was State of Mind suggestions! Let's continue with the improvements we've made to the Motion Activity suggestions.

In iOS 17.2, we had introduced the Motion Activity suggestions for people who engage in long walks but don't track them as a workout. This type of suggestion is phone based only, tracks your steps, and in iOS 18, we're introducing run and mixed walk/run activities! This type of suggestions remains available beneath the Activity switch, under journaling suggestions settings. And just like before, this type of suggestion can be combined with the photos the user takes, or the music they listen to.

In addition to the step count, the icon url and the timestamp, the Motion Activity asset now gets an additional field for the movement type. This is telling your application if the detected activity was a walk, a run, or a mix of both activities. And of course, each movement type comes with it's own image.

In order to add State of Mind assets content, you first retrieve all the content of type JournalingSuggestion.MotionActivity in a suggestion.

Then again, you can simply convert the asset in an AsyncImage using the item icon.

And for this example, we will also add a text representation of the motion activity via a custom function.

The getMotionActivityLabel function could again be very simple, checking on the movement type and special casing for running, walking, or mixed walk and run. And that's all you need to leverage the new Motion Activity content! Let's check out the result for this example.

This simple example shows an asset picked by the user with the new "Running" Motion Activity movement type. And that was Motion Activity suggestions update! Continuing with a completely new type of suggestion we call Generic Media. In iOS 17.2 we introduced Song and Podcasts assets, a category of assets that focused on the music and podcasts you listen to on Apple Music and Apple Podcasts.

In iOS 18, we also support other media applications that deliver music or podcast content to users. For example, if a person using your App is a fan of Melody123, or EnlightningTalks Apps, then the content they listen to can be surfaced as part of their journaling suggestions. Of course, sometimes applications can deliver both music and podcasts. That's why we call this type of suggestion Generic Media, and we represent them with the icon of the application used to consume the media.

This remains controlled under the Media journaling suggestions settings.

Also remember, the applications that provide media content can choose not to participate in journaling suggestions, for more information refer to the Now Playing API.

This new Generic Media asset type comes with the title of the media, an artist name, an album name, the app icon and a timestamp.

In order to add the generic media assets content, you first retrieve all the content of type JournalingSuggestion.GenericMedia in a suggestion.

Then you can simply convert the asset in an AsyncImage using the app icon of the app that was used to consume this media.

And for this example, we display title, artist and album when they are available.

Keep in mind, none of those fields are guaranteed, it depends on what the donating app is providing. So be sure to verify if those fields exist before using them. And now, let's check out the result for this example.

Let's run this now! In this case, we picked a suggestion with Generic Media content from the Melody123 example App as shown by its icon, and our App received playback details from a song including its title, artist and album name.

That's how you support media content from your users favorite apps! And now let's look into the last addition for this release, the Reflection suggestions.

Reflection suggestions are general prompts to help you reflect on gratitude, kindness, purpose and more. The prompts are inviting, usually setting up the frame for a theme, and asking you a question about it. Unlike sensed suggestions that are made of how you engage with the world, reflection prompts are universal and atemporal, meaning that you could reflect through them anytime, even come back to them at some cadence. Those suggestions are enabled by default, but are controlled by a new Reflection Prompts toggle under Journaling Suggestions settings. It's also worth noting that the suggestion sheet will show a few suggestions of that type in the recommended tab, and in order for users to pick what's just right for them, each suggestion comes with a button to cycle through different prompts.

When a user selects a reflection prompt, your application will receive a JournalingSuggestion.Reflection asset. This asset is very simple to handle, it simply contains the prompt string that the user chose. You also get the color that was used on the sheet to present this prompt, so that you can match this experience in your application.

In order to add reflection prompt assets content, you first retrieve all the content of type JournalingSuggestion.Reflection in a suggestion.

Then for each of them, you can show them with a Text element leveraging the prompt property.

In this example, I also use the provided background color, and choose a foreground color accordingly with the getForegroundColor function.

Again, getForegroundColor can be very simple logic Checking if the brightness of the background color is above or below average.

Let's run this now! In this example, the picked suggestion carries Reflection content with a dark color and our prompt text renders in a contrasting white foreground.

The reflection prompts strings could be used by your users as a starting point for helpful expressive writing journaling experiences.

This closes how you can handle the new reflection suggestions! And now, I'm sure you want to get your application ready by the time iOS 18 ships to everyone. So let's continue with best practices. Adopting the latest additions of the API, will allow your application to leverage the new content that users can choose to send to your applications with full resolution. You can make the best use of every field we provide, and really specialize the experience in a way that fits your application. If your application does not adopt the new API, then some of the content returned in the completion block may be ignored by your app, and this might surprise the user! But you can also make your app more robust to upgrades by supporting fallback asset types such as UIImage and Image. That way, your app will have some level of support, even if you don't process all of the available fields right away. Also keep in mind, the user is in control of what they share with your application: - they choose what content gets included in their suggestions, during onboarding or under privacy settings, - they choose what suggestion to send to your application, - they choose what assets to include or not include before sending to your application. While this is controlled by your users, it drives what your application receives. Wrapping up on Journaling Suggestions updates, you're ready to upgrade the experience of your users with State of Mind, Generic Media, Motion Activity and Reflection Prompts. This will take them to the next level! And If your application supports landscape, you can check it out today, no change required to your application! And of course, share your feedback with us.

We're really excited about all you're going to build with this new version of the API!