Just call us, we'll might call you - How to add Pictures Lab to your App

Windows Phone 8 introduced a nice new feature called File and Uri associations. This feature makes it possible to register an app for certain file extensions and Uri protocols. A couple of apps already support it and Nokia has a nice site which lists a couple.

Pictures Lab recently added support for that as well and uses it to call the app Instagraph. This means with the help of that app Pictures Lab now provides posting / sharing on Instagram. But that's not all, Pictures Lab also supports inbound Uri associations, so you can pass an image to Pictures Lab through the mechanism of an Uri association pretty easily.




How it works
In order to call Pictures Lab from an app this scheme has to be used:

pictureslab:edit?Name=fileNameinthemedialib[&ClientId=ProductIdFromStore]
or
images:edit?Name=fileNameinthemedialib[&ClientId=ProductIdFromStore]

• fileNameinthemedialib:
  This is the filename of the image in the Media library / Pictures Hub. It does not matter if the file extension like .jpg is provided or not. 
• ClientId:
  This is an optional parameter. If it's provided then it should be the GUID that also matches the store product Id. It's not used in Pictures Lab now, but might be useful in the future to know the source of the protocol call and one could also use it to build a link like that: http://www.windowsphone.com/s?appid=ClientId

or to just launch Pictures Lab without passing an image:
pictureslab:launch

Sample code:

var photoChooser = new PhotoChooserTask();
photoChooser.Completed += async (sender, e) =>
{
   // When the user selected a photo, pass the filename on to Pictures Lab for editing
   var uri = string.Format("images:edit?Name={0}&Clientid={1}", 
             System.IO.Path.GetFileName(e.OriginalFileName), 
             "9902dac1-c001-440b-add5-f38446b35676");
   // uri = "images:edit?Name=WP_20130527_009&Clientid=9902dac1-c001-440b-add5-f38446b35676" 
   var wasSuccess = await Windows.System.Launcher.LaunchUriAsync(new System.Uri(uri));
};
photoChooser.Show();

Note, it's not necessary to UrlEncode the Uri, the Windows Phone platform handles it automatically. If the user has Pictures Lab not installed and the above Uri is called, the Windows Phone OS is also smart enough to show the user a dialog which asks to search for an app in the Store that can handle the protocol. This will bring up Pictures Lab.

Conclusion
The concept of Uri associations is like the little brother of Windows 8's Share Charm, but it's still quite powerful and gives us app developers a nice way to combine our apps and make it a seamless UX. It's a win for the user and therefore it could be a win-win situation for the involved apps.

Future
For a next version I'm also thinking about a callback scenario. The user story would be: A user opens app A and wants to edit an image, this will open Pictures Lab, when the user is done with editing, Pictures Lab will call app A again. The user is back in app A with the edited image.
This callback mechanism would probably use a Callback parameter in the scheme above where app A can provide the UrlEncoded callback Uri with a placeholder for the edited pictureName. Something like that:

images:edit?Name=MyInputImageName.jpg&Callback=myapp%3Apost%3FName%3D%7B0%7D
The Url decoded part of the Callback: myapp:post?Name={0}
This callback format string will be used in Pictures Lab to call app A and pass the edited picture back.

Makes sense?
Please let me know your thoughts and if that would be useful. Feel free to comment or reach out to me through any channel.