Synchronizing App Preferences with iCloud アプリ環境設定を iCloudと同期する

Overview 概要

This sample demonstrates how to store preference, configuration, and app-state data in the iCloud key-value store using the NSUbiquitousKeyValueStore class. You can then share this data with every instance of your app on every device connected to a userʼs iCloud account. この見本コードは、どのように環境設定、構成設定、そしてアプリ状態データをiCloudキー値ストアの中にNSUbiquitousKeyValueStoreクラスを使って格納するかを実演します。あなたはそれからこのデータを、あるユーザのもつiCloudアカウントに接続されたあらゆる機器上のあなたのアプリのあらゆるインスタンスで共有できます。

In this sample the user picks a background color. App instances running on other devices that are logged in with the same iCloud account are then notified of the color to match. この見本ではユーザは背景色を選びます。同じiCloudアカウントでログインされる他の機器上で動作しているアプリインスタンスは、そのとき色を合わせるよう通知されます。

The key-value store is not a replacement for UserDefaults or other local techniques for saving the same data. The key-value store’s purpose is to synchronize key-value data between app instances running on different devices of the same user. If iCloud is not enabled or is not available on a given device, the app still keeps a local copy of the data in NSUserDefaults. キー値ストアは、UserDefaultsのまたは同じデータを保存するその他の機械室の代わりではありません。キー値ストアの目的は、キー値データを同じユーザのいくつか異なった機器上で動作しているアプリインスタンスそれらの間で同期することです。iCloudがある与えられた機器上で作動されないまたは利用可能でないならば、アプリは依然としてデータのローカルコピーをNSUserDefaultsにおいて保ちます。

Configure the Sample Code Project 見本のコードプロジェクトを構成設定する

To configure your Xcode project first you need change the Bundle Identifiers for both macOS and iOS targets to match your own. Next, to work with iCloud and NSUbiquitousKeyValueStore, you need set up an iCloud key-value store ID for both targets. This sample already has the both targets’ iCloud capabilities set up, with the PrefsInCloud.entitlements file already created. You need to fill in your own key-value store IDs in those entitlement files to complete the configurations. あなたのXcodeプロジェクトを構成設定するには最初にあなたはBundle IdentifiersをmacOSとiOSターゲットの両方に対して変更してあなた自身に合ったものにする必要があります。次に、iCloudとNSUbiquitousKeyValueStoreを扱うために、あなたはiCloudキー値ストアIDを両方のターゲットに対して準備する必要があります。この見本は、すでに両方のターゲットのもつiCloud適応性を準備済みです、すでに作成されたPrefsInCloud.entitlementsファイルで。あなたは、あなた自身のキー値ストアIDをそれら資格ファイルに記入して、構成設定を完了する必要があります。

For each target (iOS and macOS): 各ターゲット（iOSとmacOS）に対して：

1. In the Xcode project, open the target’s PrefsInCloud.entitlements file. Xcodeプロジェクトにおいて、ターゲットのもつPrefsInCloud.entitlementsファイルを開いてください。

2. In that file, go to com.apple.developer.ubiquity-kvstore-identifier entitlement and replace $(CFBundleIdenfier) with your key-value store ID (i.e. $(TeamIdentifierPrefix)<your key-value_store ID>). For example if your key-value store ID is “com.mycompany.myKeyValueStoreID” it would look like this: $(TeamIdentifierPrefix)com.mycompany.myKeyValueStoreID. It’s important that the key-value store ID portions are the same between both targets. そのファイルにおいて、com.apple.developer.ubiquity-kvstore-identifier資格に行き、そして$(CFBundleIdenfier)をあなたのキー値ストアID（たとえば、$(TeamIdentifierPrefix)<your key-value_store ID>）と置き換えてください。例えばあなたのキー値ストアIDが “com.mycompany.myKeyValueStoreID” であるならば、それはこのように見えるでしょう：$(TeamIdentifierPrefix)com.mycompany.myKeyValueStoreID。重要なのは、キー値ストアIDの各部が両方のターゲットの間で同じであることです。

In addition to configuring the project, you need to configure the devices in which the project runs. プロジェクトを構成設定することに加えて、あなたはプロジェクトが動作する機器を構成設定する必要があります。

To configure the iOS and macOS devices, verify that iCloud Drive is turned on. Then log into both devices with the same iCloud account. iOSとmacOS機器を構成設定するには、iCloud Driveが入りにされることを確かめてください。それから両方の機器に同じiCloudアカウントでログインしてください。

Build and run the app to install it on both devices, and then do the following: アプリをビルドおよび実行して、それを両方の機器にインストールしてください、それから以下を行ってください：

• iOS: Tap the action button at the top right to pick the desired background color. iOS: アクションボタンを上右でタップして、望む背景色を選択してください。

• macOS: Choose the desired background color from window’s popup menu. macOS: 望む背景色をウインドウのポップアップメニューから選んでください。

The desired color represents a value (numbered 0 to 3) which is uploaded to iCloud. App instances running on the other devices logged into the same iCloud account are notified to match that specific background color. 望んだ色は、ある値（番号０から３）を表します、それはiCloudにアップロードされます。同じiCloudアカウントにログインした他の機器上で動作しているアプリインスタンスは、その特定の背景色に合わせるよう通知されます。

Register to Respond to Key-Value Store Changes キー値ストア変更に応答するために登録する

The sample uses NotificationCenter to register as an observer to the notification didChangeExternallyNotification. The following example installs the app as the observer to respond to the key-value store changes: この見本は、NotificationCenterを使って、あるオブザーバとして通知didChangeExternallyNotificationに登録をします。以下の例は、アプリをオブザーバとしてインストールしてキー値ストア変更に応答します：

NotificationCenter.default.addObserver(self,
    selector: #selector(ubiquitousKeyValueStoreDidChange(_:)),
    name: NSUbiquitousKeyValueStore.didChangeExternallyNotification,
    object: NSUbiquitousKeyValueStore.default)

Immediately following the call to addObserver, obtain the key-value store changes since last launch by calling synchronize(). The operating system controls when keys and values are uploaded to iCloud. Calling synchronize() simply stores a local cache of them and notifies iCloud of new data waiting to be uploaded. addObserverへの呼び出しに続いて直ぐに、最後の起動から後のキー値ストア変化をsynchronize()を呼び出すことによって入手してください。オペレーティングシステムは、いつキーと値がiCloudにアップロードされるかを制御します。synchronize()を呼び出すことは、単にそれらのローカルキャッシュを格納します、そして新しいデータがアップロードされるのを待っていることをiCloudに通知します。

Respond to Key-Value Store Changes キー値ストア変化に応答する

The sample uses NSNotificationCenter to register as an observer to the notification didChangeExternallyNotification to detect for value changes in iCloud. この見本は、NSNotificationCenterを使って、あるオブザーバとして通知didChangeExternallyNotificationに登録して、値の変化をiCloudにおいて検知します。

The sample implements the function ubiquitousKeyValueStoreDidChange for listening for key-value notification changes. This function is called when the key-value store in the cloud has changed externally. It replaces the old key-value color with the new one. Additionally, this function updates the NSUserDefaults key-value. 見本は、関数ubiquitousKeyValueStoreDidChangeを、キー値通知変化に聞き耳をたてるために実装します。この関数は、キー値ストアがiCloudにおいて外部から変更された時に呼び出されます。それは古いキー値の色を新しいもので置き換えます。加えて、この関数はNSUserDefaultsキー値を更新します。

This sample examines the reason for the change through the use the NSUbiquitousKeyValueStoreChangeReasonKey from the notification’s userInfo. この見本は、変更の理由を、NSUbiquitousKeyValueStoreChangeReasonKeyを通知のもつuserInfoから使うことを通して調べます。

guard let userInfo = notification.userInfo else { return }
      
// Get the reason for the notification (initial download, external change or quota violation change).
guard let reasonForChange = userInfo[NSUbiquitousKeyValueStoreChangeReasonKey] as? Int else { return }

The reason for the key-value notification change is one of the following: キー値通知変化の理由は、以下のうちの１つです：

• NSUbiquitousKeyValueStoreServerChange: Value(s) were changed externally from other users/devices. NSUbiquitousKeyValueStoreServerChange：値（複数）が他のユーザ／機器から外部的に変更された。

• NSUbiquitousKeyValueStoreInitialSyncChange: Initial downloads happen the first time a device is connected to an iCloud account, and when a user switches their primary iCloud account. NSUbiquitousKeyValueStoreInitialSyncChange：ある機器がiCloudアカウントに接続される第１回目に、そしてあるユーザが彼らの主要iCloudアカウントを切り替える時に初期ダウンロードが発生した。

• NSUbiquitousKeyValueStoreQuotaViolationChange: The app’s key-value store has exceeded its space quota on the iCloud server. NSUbiquitousKeyValueStoreQuotaViolationChange：アプリのもつキー値ストアが、iCloudサーバー上のそれの容量割当を超過した。

• NSUbiquitousKeyValueStoreAccountChange: The user has changed the primary iCloud account. NSUbiquitousKeyValueStoreAccountChange：ユーザが主要iCloudアカウントを変更した。

To obtain key-values that have changed, use the key NSUbiquitousKeyValueStoreChangedKeysKey from the notification’s userInfo. 変更されたキー値を入手するには、キーNSUbiquitousKeyValueStoreChangedKeysKeyを通知のもつuserInfoから使ってください。

guard let keys =
          userInfo[NSUbiquitousKeyValueStoreChangedKeysKey] as? [String] else { return }

let possibleColorIndexFromiCloud =
          NSUbiquitousKeyValueStore.default.longLong(forKey: gBackgroundColorKey)