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

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

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

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

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

لا يتم عادةً تنفيذ DataItem مباشرةً. بدلاً من ذلك، اتّبِع الخطوات التالية:

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

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

لمزيد من المعلومات، اطّلِع على تطبيق DataLayer Sample.

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

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

لاستخدام خريطة بيانات:

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

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

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

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

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

private fun increaseCounter(): Task<DataItem> {
    val putDataReq: PutDataRequest = PutDataMapRequest.create("/count").run {
        dataMap.putInt(COUNT_KEY, count++)
        asPutDataRequest()
    }
    return Wearable.getDataClient(this)
        .putDataItem(putDataReq)
}
DataLayerActivity.kt

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

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

ضبط أولوية DataItem

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

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

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

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

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

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
        }
    }
}
DataLayerActivity.kt

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

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