Skip to content

TMSFMXNativeiCloud

Usage

The TMSFMXNativeiCloud component is used to access the iCloud key-value store. You typically use this component to make preference, configuration, and app-state data available to every instance of your app on every device connected to a user’s iCloud account. More information about the iCloud key-value store can be found on the following page:

https://developer.apple.com/library/mac/documentation/General/Conceptual/iCloudDesignGuide/Chapters/DesigningForKey-ValueDataIniCloud.html

Methods

Methods name Description
AddKey Adds a new key with a specific name and value to the iCloud key-value store.
KeyByName Retrieves the key from the key collection after the keys have been loaded from the iCloud key-value store.
KeyValues[AKeyName] Accesses the key value after the keys are loaded from the iCloud key-value store.
RegisterForKeyUpdates Enabled by default through the AutoSynchronize property. Can be used to register the application to the notification center to receive iCloud key-value store updates.
RemoveAllKeys Removes all the keys from the iCloud key-value store.
RemoveKey Removes a specific key from the iCloud key-value store.
RemoveKeyByName Removes a specific key from the iCloud key-value store based on the name.
SynchronizeKeys Starts an asynchronous synchronize operation to retrieve the changed, keys from the iCloud key-value store.
UnRegisterForKeyUpdates Used to unregister the application and no longer receive iCloud key-value store updates. The updates can be fetched manually by calling UpdateKeys.
UpdateKeys Forces a synchronize operation and retrieves all keys from the iCloud key value store.

Properties

Properties name Description
AutoSynchronize Turn the automatic synchronization of keys on or off.
Keys Public access to the key collection synchronized with the iCloud key-value store.

Events

Events name Description
OnAccountChanged Event called when the iCloud account changed on the user device.
OnKeyAdded Event called when a key has been added from another location.
OnKeyRemoved Event called when a key has been removed from another location.
OnKeysChanged Event called when the key collection has changed.
OnKeyUpdate Event called when a key store in the collection has changed.
OnQuotaViolation Event called when the total available key-value store size has been exceeded. The key(s) that exceed this limited size will not be added to the iCloud key-value store.

Supported types

The TMSFMXNativeiCloud component keeps the iCloud keys synchronized (optionally with the AutoSynchronize property) with the key-value store. Each key has a Value property of type TValue. The supported types are Integer, Double, Boolean, String and TMemoryStream. There are multiple ways of persisting and retrieving the data. The methods and functions that can be used to perform this task are listed in the above table.

Entitlements

Before iCloud can be used in your application you need to enable it and sign your application. Additional information about enabling iCloud and incorporating it into your application can be found on the following page:

https://developer.apple.com/library/ios/documentation/General/Conceptual/iCloudDesignGuide/Chapters/iCloudFundametals.html

After reading the guide, you will need to perform 2 steps: signing your device, and adding an entitlements file that adds the necessary keys to gain access to the iCloud storage. As a helper sample we have included an iCloud demo project that demonstrates how the Entitlements file is added.

When opening the Entitlements file (iCloud.entitlements) you will notice placeholders that need to be filled in with a combination of the Team-ID and the Bundle Identifier

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>get-task-allow</key>
   <true/>
   <key>com.apple.developer.ubiquity-container-identifiers</key>
   <array>
     <string>$(TeamIdentifierPrefix)com.mycompany.myapplication</string>
   </array>
   <key>com.apple.developer.ubiquity-kvstore-identifier</key>
   <string>$(TeamIdentifierPrefix)com.mycompany.myapplication</string>
</dict>
</plist>

The first key is to allow the debugger to access the application. This is inherited from the default entitlements file that is distributed when deploying your application. The com.apple.developer.ubiquity-container-identifiers and the com.apple.developer.ubiquity-kvstore-identifier keys are used to access iCloud. Here you need to specify the correct Team Identifier Prefix and the Bundle Identifier that matches your Application ID, used in the generation of the provisioning profile. Below is a sample of the Application ID at developer.apple.com, used to generate a provisioning profile to sign your application.

TMSFMXNativeiCloud

If the prefix is ABC123 and the ID is com.tmssoftware.FireMonkeySample. The correct Entitlements.plist file would have ABC123.com.tmssoftware.FireMonkeySample as substitute for $(TeamIdentifierPrefix)com.mycompany.myapplication.