TTMSFMXNativeiCloud
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:
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:
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.
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
.