Sharing from your app

In Windows 8, sharing is a ubiquitous experience and a natural user expectation. Users often come across content in your app that they’re excited to share with friends or use in another app. As a developer you can meet this user expectation by using the Share contract which provides a lightweight, contextual and easy model for accomplishing app-to-app sharing.

You may be familiar with the app Food with Friends, introduced in the post on Creating apps that stand out from the crowd. In this post, we talk more about how an app can be a great share source using Food with Friends as an example. We will reference the views, hierarchy and the “best-at” statement of the app to guide us in the design and technical decisions involved in building a great share source experience.

Views and hierarchy of Food with Friends

What is Share and why is it important?

As shown in the Embracing UI on demand post, Windows 8 introduces charms as a convenient place for entry points into ubiquitous actions, such as searching, sharing, connecting to settings and devices across apps and with Windows. Contracts help fuel the power of these quick-access entry points to let the content in your app shine. Share is one of these contracts and its purpose is to let users do more with your content by sharing from your app to other apps.

An end-to-end sharing experience in Windows has two components. First, there is a source app that makes its content available in different formats. Next, there is a target app that registers to recognize certain formats and acts as the destination for the content being shared. Windows creates a channel of communication between the source app and the target app via the Share contract. When your app is a share source, users can confidently rely on the Share charm for finding the list of apps, friends, and other places that can consume the content from your app in the Share pane. Here’s an example.

Share pane showing a list of target apps that can receive the web
page being shared from the source app, Internet Explorer in this case.

App-to-app sharing via the Share contract is an incredible opportunity in a few ways.

First, it takes advantage of a diverse ecosystem of apps. By scanning the categories of apps in the Store, you can already begin to identify how the value proposition of a food and dining app is different from that of a productivity app or a social app and so on. Even within these categories, apps will differentiate themselves in more ways that can be listed. Your app can use what these other apps are best-at by sharing content to these apps, thus making the end-to-end user experience even more powerful.

Second, a predictable entry point for sharing in the OS means that you no longer have to take up valuable screen area within your app’s UI for share widgets, plus it’s easier for users because they don’t have to worry about finding these entry points in each app. Being able to share from your app without switching context to another app is great from the user’s perspective as it allows them to be more focused. This is also valuable in keeping the user immersed in your app’s experience.

Finally, by participating in the Share contract your app is always relevant and connected to a growing ecosystem of apps. Additionally, you don’t have to learn or integrate with each individual or new third-party API because the Share contract creates a common language for exchanging data between source and target apps.

Tailoring the Share source experience

With the Share system in Windows 8, your app can create a rich sharing experience by tailoring the content that is being shared from your app, based on the view of the app that the user is interacting with. This helps meet the user’s expectations about what is being shared from any given app view. For example, in Food with Friends, the content of the landing page is different from the content in the My Wishlist section or the Restaurant Details view. So, a user expects both the app and the system to be smart about sending and receiving the content that is relevant in the current view. Tailoring doesn’t mean having to think about every single app that is viable target for receiving content, but providing multiple representations of the shared content from your app to scale to a diverse set of app-to-app sharing scenarios.

In the next sections we take a look at how to set up your app to be a Share source, and building a tailored data package and experience for a few different views in the app.

1. Sharing tonight’s plan from the landing page
2. Sharing helpful error states from views that don’t have content to share
3. Sharing user selections from My Wishlist.

Let’s dive in.

Implementing a Share source

In Windows 8, you can use the sharing APIs to enable your app to share content with other apps. First, you need to decide which data formats and data types to implement. With Share, you can package the data in standard data formats such as text, URI, HTML, bitmap and files and in custom data formats specified on http://schema.org. In the next sections, we focus on why and how Food with Friends should support these formats.

After you've made the decision about which data formats to provide, use the classes from the Windows.ApplicationModel.DataTransfer namespace to package up the data. The DataPackage is the fundamental unit of data exchange through the Share contract.

When the user brings up charms and selects Share, your app receives the datarequested event. Your app can listen for the datarequested event and build a data package that can be sent to the target app. See this quickstart guide for details on how to set up your app for listening and responding to this event.

Sharing tonight’s plan

Here is the view that represents what this app is best at, the landing page where you’re formulating tonight’s plan.

Landing page showing Tonight’s plan in Food with Friends

Food with Friends has tailored the design of the landing page to make sure that content shines and distractions are minimized. As discussed in Creating Metro style apps that stand out from the crowd, this content makes it clear what the app is best at. In the same way that the design of the page helps the user understand the app’s purpose, it also makes it obvious that tonight’s plan is the shareable content on this page. So, the user can naturally expect that content from the Tonight section will be shared from the source app and received by the target app via Share. Understanding this user expectation is important for you as a source app developer because it helps you build a data package that matches this user expectation and intent to share. Now, we use the design of the landing page to guide us in creating an intuitive share experience using content from the Tonight section.

Scenarios

Let’s make a list of some interesting ways in which the user may want to share content from the Tonight section of Food with Friends with other apps.

1. Share tonight’s plan with a social networking app. Social networking apps are best at helping the user stay connected with a broad set of friends or followers. With app-to-app sharing, the user can share content from Food with Friends with their network and personalize it with a status update, tweet or message -“Highly recommend Southwestern Seafood – great dinner tonight!”
2. Share tonight’s plan with a calendar app. Calendar apps are best at helping the user in organizing their time and reminding them about upcoming appointments. The user can share their plan for tonight from Food with Friends to their calendar app and get a convenient reminder from the calendar app to get to the restaurant in time. Thus, the source app and the target app together fulfill an end-to-end user scenario.

As you can imagine, this list isn’t exhaustive. It’s only the beginning of a large list of app-to-app sharing scenarios. One of the advantages of using the Share platform in Windows is that you don’t have to anticipate every single app-to-app sharing scenario. But the list is valuable because it helps you as a developer of the source app identify and prioritize which data formats to share from your app to satisfy your preferred user scenarios. Now let’s take a look at how you can build a data package using standard and custom formats.

Building a data package

Which data types should you support?

You must decide which data formats you will provide in the data package. For a successful share operation, the target app must recognize the data format your app supports.

The standard data types are frequently used and recognized across a broad set of target apps. For example, many apps offer info through text, and users should be able to share this text with other apps. Targets such as note-taking apps or email apps can receive shared text from your app to complete end-user scenarios. In addition, you can also specify custom data formats for particular end-user scenarios. Choosing data formats describes these formats in more detail. We discuss how to build a data package using both standard and custom data formats for Food with Friends.

We recommend that you provide the shared content in as many data formats as you can to maximize the set of target apps that will recognize the content from your app. In supporting multiple data types, it’s important that each data type represents the same information. This parity creates user confidence and predictability in the content that is being shared from the app while allowing target apps to use this content in targeted and creative ways. But don’t provide data types that don’t accurately reflect the user’s intent in sharing.

For example, when sharing from the Food with Friends landing page, we build a data package with text, URI, HTML, files and custom formats. We won’t provide a bitmap because the pictures in the Tonight section showing food, the map, thumbnails of contacts or other images don’t help represent tonight’s plan.

Standard data formats

The standard data formats that source apps can share are:

• Text
• URI
• Bitmap
• HTML
• File

Packaging the data for tonight’s plan

As mentioned earlier, the design of the landing page emphasizes Tonight’s plan by presenting it foremost in the ListView control and minimizing other distractions. It brings forth different aspects of the plan: date and time, venue, people and so on. When the user shares from this view, they expect to use this info in another app, be it for social networking, calendars, reminders or email.

Landing page for Food with Friends featuring the Tonight section foremost in the ListView control

This guide on Sharing content provides an overview of how to set the data in the package for these standard data types. Later we deconstruct the content of the Tonight section to explain how to represent this information meaningfully in the data package. The information contained in each data type is wholly representative of tonight’s plan. This ensures that no matter what data type the target app chooses to accept, the fidelity of the information isn’t lost.

Text

Sharing text is great when you want the content of your app to be available to a large set of apps, because it is a commonly recognized format. In this scenario, the text in the data package must provide all the key info for the plan, i.e. where, when and with whom, and URI, as shown here:

URI

We recommend that you provide a web link for the content being shared from the app. This is to ensure that users who are viewing the content from a PC without Windows 8 or without your app can still view the shared content. In case there is no web URI available, you can provide a deep-link to the content in your app. For Food with Friends, the app shares a URI to Tonight’s plan on the Food with Friends website.

Bitmap

Not applicable, because an image here does not help convey the plan.

HTML

The HTML contains markup of the formatted version of the information passed in through the other data formats. It represents key information about tonight’s plan: i.e. where, when, with whom.

File

Sharing files that represent the content being shared in the relevant formats allow target apps to work with these file types. For example, Food with Friends can use tonight’s plan in .ics, .vcs or other standard file formats that represent an event. This allows calendar or reminder apps that recognize these popular formats to create events.

Now, when the user selects Share, they see a filtered list of target apps that recognize the shared data. The user can select the People app to share the content of tonight’s plan with their connected social network.

Food with Friends sharing to the People app

Custom data formats

Some target apps register to accept specific data formats to support targeted scenarios. For example, a calendar app may choose to support an Event data format or a Maps app may choose to support a Placedata format. In a source app you can support sharing additional formats to enable your users to complete these targeted scenarios.

Recognized custom data formats

In deciding what custom data formats to support, it’s natural to ask if there are recognized formats that are understood across apps. Check out the existing schemas on http://schema.org/ to ensure that the data types that your apps send and receive are universally recognized. This website provides a collection of schemas, i.e. structured data types that are commonly used across a breadth of industries. As an example, some common data formats supported in this standard are Person, Place,Restaurant, Event, Product and many more. With source and target apps having a common set of data formats that they recognize and exchange, the possibilities of app-to-app sharing are infinite.

Packaging the data for tonight’s plan

Now that you are now familiar with building a data package with standard data formats, let’s take a look at how to think about adding custom data formats to your data package for targeted user scenarios that require such rich data formats.

In the Scenarios section earlier, we identified a category of apps, namely the calendar and planning category that we want to connect Food with Friends to. For doing so, we can reference the existing schemas on schema.org to find a data format that represents the information we want to share and that would be recognized by the apps we’re trying to target. Given that we’re trying to share content from the Tonight section in the landing page, we can support sharing the Event format in the data package. This enables users to share their plan with calendar and planning apps that recognize this format. The images show the end-to-end experience for the user with the two apps: when the user swipes in from the edge and taps on share, they see a filtered list of target apps that they can share tonight’s plan to. The list is populated with any apps that have registered to support the Event format in the Share target contract. You can tap the calendar app, preview the appointment you’re about to share and then send tonight’s plan to your calendar from app’s target view. This is quick and efficient and lets the user get right back to using Food with Friends.

Landing Page with the Share charm showing a calendar app as a Share target

View of a calendar app displaying the Share data from Food with Friends in the form of an event

For now, we won’t go into the design or technical details of the calendar app’s target app view. See Receving shared content to learn more about implementing a Share target.

Data package properties

The DataPackage class supports a collection of properties of type DataPackagePropertySet to describe the data contained in the package. Target apps can use these properties to learn more about the content of thedata package. Examples of common properties include thumbnail images, title, and file types. We recommend that you set these properties in the data package.

Here are the some properties in the data package when sharing from tonight’s plan.

• Title – “Tonight’s plan”

• Description– “Dinner at Southwestern Seafood”

• Thumbnail– a smaller image representing an event or plan.

See the DataPackagePropertySet class details to learn how to add properties to your data package.

Sharing error states

In the example we just looked at, we demonstrate how you design and implement a share source experience for the Tonight section on the landing page.

This leads to the questions. What if the plan doesn’t exist yet? What would you share? The next image shows the landing page for Food with Friends, when event planning has not started.

Landing page view without any events planned

As you can see, the hub view shows a few sections, namely a template for making tonight’s plan, Friends’ Wishlists, My Wishlist and if you scroll further, the All Restaurants view. But when no event has been created for tonight, there is nothing in this view to share.

How then do you respond to the datarequested event without having a meaningful data package to hand to the Share manager?

In such a case, where sharing cannot be meaningfully completed in the current view, the app should show an error message that tells the user what they need to do to enable sharing in that view. You can do this by calling the FailWithDisplayText method on the DataRequest class. This method cancels the share operation and supplies a text message to the Sharing Manager. The Share pane app can then display this text to the user to explain why the share operation failed. You can learn more about implementing this custom error message in DataRequest.FailWithDisplayText.

In the view above, when the user tries to share content via the share charm, the app returns this error message:

“You have no plans for tonight. Create a plan to share from this view.”

This allows the user to take the necessary steps to make tonight’s plans and thus enable sharing.

Landing page showing the Share charm displaying the error provided by the app

Similarly, in other views where sharing cannot be supported; we recommend that you tailor the error message the app returns for the current view. As another example, if the user hasn’t logged in to the app yet, the app may return an error message that specifically asks the user to log in before they can share content.

Ultimately, make sure the error text provided to the user is helpful in enabling them to share from the app.

Sharing user selections

When the user has selected specific items in your app’s view, you can reflect this user intent in the share experience from your app by building and sharing data packages that best represent those selected items.

In this view in Food with Friends, the user has curated a set of restaurants that they want to dine at. The user might want to select a specific restaurant and share it with any number of restaurant-based apps.

My wishlist view of Food with Friends with a restaurant selected

When the user selects a restaurant from this view, we can support sharing the Restaurant format in the data package as described earlier. Any target apps that recognize the format will now be available as share targets. For example, in the next image, you see the restaurant selection being shared with a note-taking app that saves the restaurant in the user’s Favorite restaurants notebook.

Note taking app displaying restaurant data in its Share view

We recommend that when the user gets back to the app after interacting with the target app, the source app preserves the selection the user made. This can help users if they want modify their selection, or share the same content with multiple targets.

Summary

Sharing content from your app can make your app central to a social and connected experience for users in Windows 8. Your app can focus on delivering rich, shareable content to the user and rely on the Share charm to minimize the overhead of integrating with each new third-party app that can receive content. By supporting sharing, your app is at a competitive advantage because sharing broadens the scope of end-to-end user scenarios possible from within the app itself.

I hope that this post helps you understand the motivation and thought process behind building a great experience for sharing from your app. I also hope this understanding coupled with your vision for what your app is best at inspires you to use this platform capability in way that creatively and uniquely meets your app’s goals. If you want to learn more about sharing, see an overview of Sharing and Exchanging Data and the Share content source sample to help you get started.

-- Ishita Kapur, Program Manager, Windows