مزامنة عناصر البيانات مع Data Layer API

تحدّد DataItem الواجهة التي يستخدمها النظام لمزامنة البيانات بين الأجهزة المحمولة والأجهزة القابلة للارتداء. يتألف DataItem عادةً من المكوّنات التالية:

• الحمولة: هي مصفوفة بايت يمكنك ضبطها باستخدام البيانات، ما يتيح لك تنفيذ تسلسل الكائنات وإلغاء تسلسلها. يقتصر حجم الحمولة على 100 كيلوبايت.
• المسار: سلسلة فريدة يجب أن تبدأ بشرطة مائلة للأمام، مثل "/path/to/data".

ملاحظة: يمكن لواجهة برمجة التطبيقات Data Layer API إرسال الرسائل ومزامنة البيانات مع هواتف Android أو ساعات Wear OS فقط. إذا كان جهاز Wear OS مقترنًا بجهاز iOS، لن تعمل واجهة برمجة التطبيقات Data Layer API.

لهذا السبب، لا تستخدِم واجهة برمجة التطبيقات Data Layer API كطريقة أساسية للتواصل مع شبكة. بدلاً من ذلك، اتّبِع النمط نفسه المتبع في تطبيقات الأجهزة الجوّالة، مع بعض الاختلافات البسيطة.

لا يتم عادةً تنفيذ DataItem مباشرةً. بدلاً من ذلك، عليك إجراء ما يلي:

1. أنشئ عنصر PutDataRequest، مع تحديد مسار سلسلة لتحديد العنصر بشكل فريد.
2. اتّصِل بالرقم setData() لضبط الحمولة.
3. إذا كان التأخير في المزامنة سيؤثر سلبًا في تجربة المستخدم، استخدِم الدالة setUrgent().
4. استخدِم طريقة putDataItem للفئة DataClient لطلب أن ينشئ النظام عنصر البيانات.

عند طلب عناصر البيانات، يعرض النظام عناصر تنفّذ واجهة DataItem بشكل صحيح. ومع ذلك، بدلاً من التعامل مع وحدات البايت الأولية باستخدام setData()، ننصحك باستخدام خريطة بيانات، التي تعرض عنصر بيانات بواجهة تشبه Bundle.

لمزيد من المعلومات، يُرجى الاطّلاع على تطبيق نموذج DataLayer.

مزامنة البيانات مع خريطة بيانات

استخدِم الفئة DataMap متى أمكن ذلك. يتيح لك هذا الأسلوب العمل مع عناصر البيانات في شكل Bundle على Android، وبالتالي ينفّذ النظام تسلسل الكائنات وإلغاء تسلسلها نيابةً عنك، ويمكنك معالجة البيانات باستخدام أزواج المفاتيح والقيم.

لاستخدام خريطة بيانات، اتّبِع الخطوات التالية:

1. أنشئ عنصر PutDataMapRequest، مع ضبط مسار عنصر البيانات.

   ملاحظة: سلسلة المسار هي معرّف فريد لعنصر البيانات يتيح لك الوصول إليه من أي من طرفَي الاتصال. يجب أن يبدأ المسار بشرطة مائلة للأمام. إذا كنت تستخدم بيانات هرمية في تطبيقك، أنشئ مخطط مسار يتطابق مع بنية البيانات.

2. استخدِم الدالة PutDataMapRequest.getDataMap() للحصول على خريطة بيانات يمكنك ضبط القيم عليها.
3. اضبط قيمًا لخريطة البيانات باستخدام طرق put...()، مثل putString().
4. إذا كان التأخير في المزامنة سيؤثر سلبًا في تجربة المستخدم، استخدِم الدالة setUrgent().
5. اتّصِل بالرقم PutDataMapRequest.asPutDataRequest() للحصول على العنصر PutDataRequest.
6. استخدِم طريقة putDataItem للفئة DataClient لطلب أن ينشئ النظام عنصر البيانات.

   ملاحظة: في حال انقطاع الاتصال بين الهاتف المحمول والأجهزة القابلة للارتداء، يتم تخزين البيانات مؤقتًا ومزامنتها عند إعادة الاتصال.

تعرض طريقة increaseCounter() في المثال التالي كيفية إنشاء خريطة بيانات ووضع البيانات فيها:

private const val COUNT_KEY = "com.example.key.count"

class MainActivity : Activity() {

    private lateinit var dataClient: DataClient
    private var count = 0
    ...
    // Create a data map and put data in it
    private fun increaseCounter() {
        val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
            dataMap.putInt(COUNT_KEY, count++)
            asPutDataRequest()
        }
        val putDataTask: Task<DataItem> = dataClient.putDataItem(putDataReq)
    }
    ...
}

public class MainActivity extends Activity {
    private static final String COUNT_KEY = "com.example.key.count";
    private DataClient dataClient;
    private int count = 0;
    ...
    // Create a data map and put data in it
    private void increaseCounter() {
        PutDataMapRequest putDataMapReq = PutDataMapRequest.create("/count");
        putDataMapReq.getDataMap().putInt(COUNT_KEY, count++);
        PutDataRequest putDataReq = putDataMapReq.asPutDataRequest();
        Task<DataItem> putDataTask = dataClient.putDataItem(putDataReq);
    }
  ...
}

لمزيد من المعلومات حول معالجة Tasks، يُرجى الاطّلاع على المستندات المرجعية.

تنبيه: قبل استخدام Wearable Data Layer API، تأكَّد من توفّرها على جهاز، وإلا سيحدث استثناء. استخدِم فئة GoogleApiAvailability، كما هو موضّح في Horologist.

تحديد أولوية DataItem

تتيح واجهة برمجة التطبيقات DataClient إرسال طلبات عاجلة لمزامنة عناصر DataItem. عادةً، يؤخّر النظام تسليم عناصر البيانات إلى شبكة Wear OS لتحسين عمر البطارية في أجهزة المستخدمين، ولكن إذا كان التأخير في مزامنة عناصر البيانات يؤثّر سلبًا في تجربة المستخدم، يمكنك وضع علامة "عاجل" عليها. على سبيل المثال، في تطبيق للتحكّم عن بُعد يتوقّع فيه المستخدم أن تظهر نتائج إجراءاته على الفور، يمكنك أن يزامِن النظام عناصر البيانات على الفور من خلال استدعاء setUrgent().

إذا لم تتّصل بالرقم setUrgent()، قد يؤخّر النظام مزامنة عناصر البيانات غير العاجلة لمدة تصل إلى 30 دقيقة، ولكن يمكنك عادةً توقّع أن يكون التأخير بضع دقائق فقط. مستوى الإلحاح التلقائي هو "غير عاجل"، لذا عليك استخدام setUrgent() إذا كنت بحاجة إلى الاحتفاظ بسلوك المزامنة الفورية من الإصدارات السابقة من Wear OS API.

الاستماع إلى أحداث عناصر البيانات

إذا غيّر أحد جانبي عملية ربط طبقة البيانات عنصر بيانات، عليك إعلام المستخدم بأي تغييرات على الجانب الآخر من عملية الربط. يمكنك إجراء ذلك من خلال تنفيذ أداة معالجة لأحداث عناصر البيانات.

يُعلم مقتطف الرمز البرمجي في المثال التالي التطبيق عند تغيُّر قيمة العداد المحدّد في المثال السابق:

private const val COUNT_KEY = "com.example.key.count"

class MainActivity : Activity(), DataClient.OnDataChangedListener {

    private var count = 0

    override fun onResume() {
        super.onResume()
        Wearable.getDataClient(this).addListener(this)
    }

    override fun onPause() {
        super.onPause()
        Wearable.getDataClient(this).removeListener(this)
    }

    override fun onDataChanged(dataEvents: DataEventBuffer) {
        dataEvents.forEach { event ->
            // DataItem changed
            if (event.type == DataEvent.TYPE_CHANGED) {
                event.dataItem.also { item ->
                    if (item.uri.path.compareTo("/count") == 0) {
                        DataMapItem.fromDataItem(item).dataMap.apply {
                            updateCount(getInt(COUNT_KEY))
                        }
                    }
                }
            } else if (event.type == DataEvent.TYPE_DELETED) {
                // DataItem deleted
            }
        }
    }

    // Method to update the count
    private fun updateCount(int: Int) { ... }
    ...
}

public class MainActivity extends Activity implements DataClient.OnDataChangedListener {
    private static final String COUNT_KEY = "com.example.key.count";
    private int count = 0;

    @Override
    protected void onResume() {
        super.onResume();
        Wearable.getDataClient(this).addListener(this);
    }

    @Override
    protected void onPause() {
        super.onPause();
        Wearable.getDataClient(this).removeListener(this);
    }

    @Override
    public void onDataChanged(DataEventBuffer dataEvents) {
        for (DataEvent event : dataEvents) {
            if (event.getType() == DataEvent.TYPE_CHANGED) {
                // DataItem changed
                DataItem item = event.getDataItem();
                if (item.getUri().getPath().compareTo("/count") == 0) {
                    DataMap dataMap = DataMapItem.fromDataItem(item).getDataMap();
                    updateCount(dataMap.getInt(COUNT_KEY));
                }
            } else if (event.getType() == DataEvent.TYPE_DELETED) {
                // DataItem deleted
            }
        }
    }

    // Method to update the count
    private void updateCount(int c) { ... }
    ...
}

ينفّذ هذا النشاط واجهة DataClient.OnDataChangedListener. تضيف الفئة النشطة نفسها كأداة معالجة لأحداث عناصر البيانات داخل الطريقة onResume() وتزيل أداة المعالجة في الطريقة onPause(). للاطّلاع على عملية تنفيذ تستخدم الصور ونماذج العرض والخدمات، راجِع تطبيق نموذج DataLayer.

يمكنك أيضًا تنفيذ أداة الاستماع كخدمة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الاستماع إلى أحداث Data Layer.