Video for this session: http://www.youtube.com/watch?v=t0MojsFRfjI Code for this session: https://github.com/xamarin/Seminars/tree/master/2012-03-22-iCloud Give your feedback on the session: http://bit.ly/xamfeedback Craig Dunn walks us through using iCloud features in your MonoTouch apps, using different techniques such as iCloud Key-Value Storage and iCloud Document Storage.

1. Xamarin
Seminar
22nd March 2012
Copyright 2012 © Xamarin Inc. All rights reserved

2. Announcements
http://xamarin.com/seminars
Xamarin
Copyright 2012 © Xamarin Inc. All rights reserved

3. Agenda
iCloud with MonoTouch
Craig Dunn
Technical Writer
Xamarin Documentation Team
craig.dunn@xamarin.com
Xamarin
Copyright 2012 © Xamarin Inc. All rights reserved

4. Introduction
This session discusses Apple’s new iOS5 iCloud
functionality and how to implement iCloud features
with MonoTouch.
We’ll cover:
• iCloud Basics & Setup
• iCloud Key-Value Storage
• iCloud Document Storage
• iCloud Backup (iOS Data Storage Guidelines)
Xamarin
Copyright 2012 © Xamarin Inc. All rights reserved

5. iCloud Basics (i)
• Remote storage & backup
• Synchronization of data across devices (iOS
& Mac OS X) but NOT conflict resolution
• OS process controls sending/receiving
Cloud
iPhone Local storage
storage Local storage
iCloud Daemon
iCloud Daemon
iCloud Daemon
Mac
Local storage
iPad

6. iCloud Basics (ii)
• 4 ways to utilize iCloud:
• Key-Value Pairs today’s
topic
• UIDocument
• CoreData another
• Individual files/folders time...

7. iCloud Setup (i)
• App ID & Provisioning Profile (developer.apple.com)
• grants iCloud support (tick the box!)
• linked to your TeamID and the BundleID
• Entitlements.plist (in your project)
• specify TeamID & BundleID
• use these keys:
com.apple.developer.ubiquity-kvstore-identifier
com.apple.developer.ubiquity-container-identifiers

9. iCloud Setup (iii)
• MonoDevelop Entitlements UI with placeholder
expansion:
• $(TeamPrefixIdentifier) automatically added
• $(CFBundleIdentifier) for the default
ubiquity-identifier
han it
E asier t ith
l ooks, w lop!
Mono Deve

10. iCloud Setup (iv)
• Don’t forget the devices!
• Same AppleID on each device

11. Key-Value Pairs (i)
• Similar to NSUserDefaults
• Simple types only (whatever works in a plist):
text, number, date
• Limited size:
• 64Kb total
• 64Kb max per key too
• Recommendation: use NSUserDefaults and
‘shadow’ with iCloud Key-Value pairs

12. Key-Value Pairs (ii)
Example creates
a ‘key’ for each
device, plus a
Shared one.

13. Key-Value Pairs (iii)
• SetString
• GetString
• Synchronize() returns false if no iCloud OR
if no updates are required
• Your app should run even if the Key-Values
are empty! (sounds obvious, but...)

14. Key-Value Pairs (iv)
• Change Notifications
Register for notification
ServerChange
InitialSyncChange
QuotaViolationChange
Tells us which keys NSArray of IntPtrs
have changed values
Loop through the
keys, get the new
values and do
something!

15. Files in the Cloud
• NSFileCoordinator & NSFilePresenter work
with the iCloud to prevent contention on the
local copy
• UIDocument hides that complexity from you!
aka UbiquityContainer Cloud
storage
Presenter / Coordinator
Local
Presenter / Coordinator
Local storage
storage
iPhone iCloud Daemon
iCloud Daemon
Mac
Presenter / Coordinator
iCloud Daemon
or just use Local
UIDocument! storage
iPad

16. UbiquityContainer Ru
ki
Bloc backg
a
all!
ng c round
n on thread!
• NSFileManager.DefaultManager.GetUrlForUbiquityContainer()
• /private/var/mobile/Library/Mobile%20Documents/
AAA7MMJKYN~com~xamarin~samples~taskcloud/
Documents/ (user-visible in Settings)
<your other stuff>
• Not to be confused with your app’s home directory
• /private/var/mobile/Applications/42871799-
F2CD-455B-9353-749B15C8AA76/
TaskCloud.app (app bundle)
Documents/ (user-visible in iTunes)
Library/
<your other stuff>

17. UIDocument (spoilers)
• Where are iCloud documents stored?
UbiquityContainer Asyn
c
• How do you create a UIDoc?
UIDoc.Save(ForCreating) Asyn
c
• How do you open one? UIDoc.Open() Asyn
• How are changes applied? your model on the UIDoc)
c
(to
• How do you save it again? UpdateChangeCount()
UIDoc.
• What if it changes elsewhere? for notification...
Listen
Asyn
c
• How do you enumerate NSMetadataQuery()
Asyn
c
UIDocs?
Asyn
c

18. UIDocument (example)

19. Finding UbiquityContainer
This one line is
key to getting Asyn
c
iCloud working!
Do this in FinishedLoading. Apple also recommends
re-checking each time the app comes to the
foreground.

20. Subclassing UIDocument
• Override the ‘read’ and ‘write’ methods:
• Actually called LoadFromContents() and
ContentsForType()
• iCloud takes care of when they’re called and
manages contention at the file system level.
• You NEVER read/write the filesystem directly!
• Save(CompletionHandler) As
ync
hro
no
• Open(CompletionHandler) us!
• UpdateChangeCount

21. Subclassing UIDocument
url to UbiquityContainer location
default value
‘Model’ can be
as simple or
complex as you
like
aka ‘Open’
So we can respond to this data
changes if we want
aka ‘Save’ accesses
the model and sends
to filesystem

22. Create a UIDoc
Put user-generated files in
the /Documents/ directory
Has the ‘(default text)’ set
Save happens Asyn
asynchronously, the c
completion handler runs
when it is done
• You could also use
NSFileManager.DefaultManager.SetUbiquitous() to
move an existing file from your home directory to
the UbiquityContainer

23. Open UIDoc
Open specific filename
from the /Documents/
directory
Asyn
c
Might need to be
run on Main thread

24. Changes Applied & Saved
UpdateChangeCount() is Update the model with
all that is required to the edited text
signal to iCloud that the
file should be saved*
* You can implement full undo/redo instead of
UIDocumentChangeKind.Done

25. Changes Elsewhere
Listen for notification sent by
the UIDocument subclass
when it is changed
When that notification
occurs, we are grabbing the
updated text and assigning it
to the UITextView *
* In a real app, you would probably want to do some
conflict resolution instead...

26. Enumerate UIDocs (i)
CloudUIDoc example
Looking for a single,
specific filename Special Predicate syntax
(monkeyDocFilename)
TaskCloud example (just to show a different query)
Looking for all Special Predicate syntax
*.task files
queryDidFinishGathering on next slide...

27. Enumerate UIDocs (ii)
When the NSMetadataQuery is done,
we stop it (it could keep running/
monitoring) and remove our listener
We expect only one file in the
example app; get its “ItemURL” then
create and open the document from
that location
• Metadata sync’s faster, so other devices will
learn if a particular file has been created (even
though they don’t know the contents)

28. Debugging Tips (i)
• The /Documents/ directory can be
managed by the user (and you, for
testing)

29. Debugging Tips (ii)
• Check your iCloud-linked Mac, sync’d files will
be there if everything is working correctly
/Users/<you>/Library/Mobile Documents/<TeamId><BundleId>/Documents

30. iOS Data Storage
Guidelines (for iCloud)
• Only documents that are user-generated should
go into /Documents/
• Data that can be re-created should go into
/Library/Caches/
• Temp data should be in /tmp/
• Use the “do not backup” attribute to prevent
ANY files being backed-up to iCloud

31. Other examples
• Key-Value ~ chat2self

32. Other examples
• UIDocument ~ TaskCloud

33. References (i)
Introduction to iOS 5 (currently being updated)
http://docs.xamarin.com/ios/tutorials/Introduction_to_iOS_5
What’s New in iOS
https://developer.apple.com/library/ios/#releasenotes/General/WhatsNewIniPhoneOS/
Introduction/Introduction.html
TaskCloud - iCloud UIDocument sample
http://conceptdev.blogspot.com.au/2012/03/icloud-uidocument-sample-taskcloud.html
https://github.com/conceptdev/taskcloud
chat2self - iCloud Key-Value sample
http://conceptdev.blogspot.com.au/2012/02/icloud-key-value-example-chat2self.html
https://github.com/conceptdev/Chat2self
iOS Data Storage Guidelines
https://developer.apple.com/icloud/documentation/data-storage/
Xamarin
Copyright 2012 © Xamarin Inc. All rights reserved

34. References (ii)
NSFilePresenter Protocol Reference
http://developer.apple.com/library/mac/#documentation/Foundation/Reference/
NSFilePresenter_protocol/Reference/Reference.html
NSFileCoordinator Class Reference
http://developer.apple.com/library/mac/#documentation/Foundation/Reference/
NSFileCoordinator_class/Reference/Reference.html
iCloud Developer Documentation
https://developer.apple.com/icloud/documentation/
Xamarin
Copyright 2012 © Xamarin Inc. All rights reserved

35. Xamarin
Seminar
Please give us your feedback
http://bit.ly/xamfeedback
Follow us on Twitter
@XamarinHQ
22nd March 2012
Copyright 2012 © Xamarin Inc. All rights reserved