إرسال الرسائل واستلامها على Wear

يمكنك إرسال الرسائل باستخدام MessageClient API وإرفاق العناصر التالية بالرسالة:

• حمولة بيانات عشوائية اختيارية
• يشير هذا المصطلح إلى مسار يعرِّف إجراء الرسالة بشكلٍ فريد.

وعلى عكس عناصر البيانات، لا تحدث أي مزامنة بين التطبيقات المحمولة والقابلة للارتداء. الرسائل هي آلية اتصال أحادية الاتجاه مفيدة لاستدعاءات الإجراءات عن بُعد (RPC)، مثل إرسال رسالة إلى الجهاز القابل للارتداء لبدء نشاط.

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

في ظل توفُّر عدة أجهزة متصلة، عليك أن تراعي تتلقى العُقد الرسائل. على سبيل المثال، في تطبيق تحويل الصوت إلى نص الذي يتلقى بيانات صوتية على الجهاز القابل للارتداء، أرسل الرسالة إلى نقطة باستخدام طاقة المعالجة والبطارية القدرة على معالجة الطلب، مثل جهاز محمول باليد.

ملاحظة: عند تحديد تفاصيل رسالتك، ضع في اعتبارك إمكانية تعدد العُقد المتصلة. تأكد من تسليم الرسالة إلى الأجهزة أو العُقد المقصودة.

راجِع نموذج التطبيق التالي للاطّلاع على أمثلة على الاستخدام: DataLayer

إرسال رسالة

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

توضّح لك الأقسام التالية كيفية الإعلان عن عُقد الجهاز التي يمكنها معالجة النشاط. واكتشاف العُقد القادرة على تلبية الحاجة المطلوبة، وإرسال الرسائل إلى العُقد.

إمكانات الإعلان

لبدء نشاط على جهاز محمول باليد من جهاز قابل للارتداء، استخدِم يجب تحميل فئة واحدة ( MessageClient) لإرسال الطلب. نظرًا لأن العديد من الأجهزة القابلة للارتداء يمكن توصيلها جهاز محمول باليد، يحتاج التطبيق القابل للارتداء إلى تحديد أن العقدة المتصلة قادر على بدء النشاط. في تطبيقك المحمول، أعلن أن العقدة التي تعمل عليها يوفر إمكانات معينة.

للإعلان عن إمكانات تطبيقك المحمول، عليك اتّباع الخطوات التالية:

1. أنشِئ ملف إعداد XML في دليل res/values/ الخاص بمشروعك. ونسميه wear.xml.
2. أضِف موردًا باسم android_wear_capabilities إلى wear.xml.
3. يمكنك تحديد الإمكانات التي يوفّرها الجهاز.

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

يوضّح المثال التالي كيفية إضافة ميزة تُسمى "voice_transcription" إلى wear.xml:

<resources xmlns:tools="http://schemas.android.com/tools"
           tools:keep="@array/android_wear_capabilities">
    <string-array name="android_wear_capabilities">
        <item>voice_transcription</item>
    </string-array>
</resources>

استرداد العُقد باستخدام الإمكانيات المطلوبة

في البداية، يمكنك اكتشاف العُقد المؤهلة من خلال استدعاء طريقة getCapability من صف واحد ( CapabilityClient). لاستخدام هذه الطريقة، يجب تطبيق Wear OS وتطبيق الهاتف. يجب أن يكون لهما معرِّف التطبيق نفسه. المثال التالي كيفية استرداد نتائج العُقد التي يمكن الوصول إليها يدويًا باستخدام إمكانية voice_transcription:

Kotlin

private const val VOICE_TRANSCRIPTION_CAPABILITY_NAME = "voice_transcription"
...
private fun setupVoiceTranscription() {
    val capabilityInfo: CapabilityInfo = Tasks.await(
            Wearable.getCapabilityClient(context)
                    .getCapability(
                            VOICE_TRANSCRIPTION_CAPABILITY_NAME,
                            CapabilityClient.FILTER_REACHABLE
                    )
    )
    // capabilityInfo has the reachable nodes with the transcription capability
    updateTranscriptionCapability(capabilityInfo)
}

Java

private static final String
    VOICE_TRANSCRIPTION_CAPABILITY_NAME = "voice_transcription";
    ...
private void setupVoiceTranscription() {
    CapabilityInfo capabilityInfo = Tasks.await(
        Wearable.getCapabilityClient(context).getCapability(
            VOICE_TRANSCRIPTION_CAPABILITY_NAME, CapabilityClient.FILTER_REACHABLE));
    // capabilityInfo has the reachable nodes with the transcription capability
    updateTranscriptionCapability(capabilityInfo);
}

لاكتشاف العُقد القابلة للارتداء عند اتصالها بالجهاز القابل للارتداء، سجّل مثال على مستمع، وتحديدًا تعبيرات OnCapabilityChangedListener لكائن CapabilityClient. يوضح المثال التالي كيفية تسجيل المستمع واسترداد نتيجة باستخدام عُقد يمكن الوصول إليها وتحتوي إمكانية voice_transcription:

Kotlin

private fun setupVoiceTranscription() {
    updateTranscriptionCapability(capabilityInfo).also { capabilityListener ->
        Wearable.getCapabilityClient(context).addListener(
                capabilityListener,
                VOICE_TRANSCRIPTION_CAPABILITY_NAME
        )
    }
}

Java

private void setupVoiceTranscription() {
    ...
    // This example uses a Java 8 Lambda. You can use named or anonymous classes.
    CapabilityClient.OnCapabilityChangedListener capabilityListener =
        capabilityInfo -> { updateTranscriptionCapability(capabilityInfo); };
    Wearable.getCapabilityClient(context).addListener(
        capabilityListener,
        VOICE_TRANSCRIPTION_CAPABILITY_NAME);
}

بعد اكتشاف العُقد المؤهلة، حدِّد مكان إرسال الرسالة. اختيار عقدة بالقرب من جهازك القابل للارتداء لتقليل توجيه الرسائل عبر عُقد متعددة. تُعرَّف العقدة القريبة بأنها عقدة متصلة بشكل مباشر إلى الجهاز. ولتحديد ما إذا كانت إحدى الأجزاء قريبة كتلك المتصلة عبر البلوتوث، يمكنك طلب Node.isNearby(). في حال توفّر أكثر من عقدة في مكان قريب، يجب اختيار عقدة واحدة عشوائيًا. وبالمثل، في حالة عدم وجود أي عقدة قادرة على مقربة، فاختر عُقدة قابلة للاستيعاب بشكل عشوائي.

يوضح المثال التالي كيفية تحديد أفضل عقدة لاستخدامها:

Kotlin

private var transcriptionNodeId: String? = null

private fun updateTranscriptionCapability(capabilityInfo: CapabilityInfo) {
    transcriptionNodeId = pickBestNodeId(capabilityInfo.nodes)
}

private fun pickBestNodeId(nodes: Set<Node>): String? {
    // Find a nearby node or pick one arbitrarily.
    return nodes.firstOrNull { it.isNearby }?.id ?: nodes.firstOrNull()?.id
}

Java

private String transcriptionNodeId = null;

private void updateTranscriptionCapability(CapabilityInfo capabilityInfo) {
    Set<Node> connectedNodes = capabilityInfo.getNodes();

    transcriptionNodeId = pickBestNodeId(connectedNodes);
}

private String pickBestNodeId(Set<Node> nodes) {
    String bestNodeId = null;
    // Find a nearby node or pick one arbitrarily.
    for (Node node : nodes) {
        if (node.isNearby()) {
            return node.getId();
         }
         bestNodeId = node.getId();
    }
    return bestNodeId;
}

أوصل الرسالة

بعد تحديد عقدة لاستخدامها، أرسل الرسالة باستخدام الفئة MessageClient.

يوضح المثال التالي كيفية إرسال رسالة إلى العقدة التي تتيح تحويل الصوت إلى نص. من جهاز قابل للارتداء. هذا الاتصال متزامن ويحظر المعالجة حتى يضع النظام الرسالة في قائمة انتظار للتسليم.

ملاحظة: لا يضمن رمز النتيجة الناجحة تسليم الرسالة. إذا كان تطبيقك يتطلّب موثوقية البيانات، ننصحك باستخدام DataItem. الكائنات أو ChannelClient إرسال البيانات بين الأجهزة.

Kotlin

const val VOICE_TRANSCRIPTION_MESSAGE_PATH = "/voice_transcription"
...
private fun requestTranscription(voiceData: ByteArray) {
    transcriptionNodeId?.also { nodeId ->
        val sendTask: Task<*> = Wearable.getMessageClient(context).sendMessage(
                nodeId,
                VOICE_TRANSCRIPTION_MESSAGE_PATH,
                voiceData
        ).apply {
            addOnSuccessListener { ... }
            addOnFailureListener { ... }
        }
    }
}

Java

public static final String VOICE_TRANSCRIPTION_MESSAGE_PATH = "/voice_transcription";
private void requestTranscription(byte[] voiceData) {
    if (transcriptionNodeId != null) {
        Task<Integer> sendTask =
            Wearable.getMessageClient(context).sendMessage(
              transcriptionNodeId, VOICE_TRANSCRIPTION_MESSAGE_PATH, voiceData);
         // You can add success and/or failure listeners,
         // Or you can call Tasks.await() and catch ExecutionException
         sendTask.addOnSuccessListener(...);
         sendTask.addOnFailureListener(...);
    } else {
        // Unable to retrieve node with transcription capability
    }
}

ملاحظة: لمزيد من المعلومات عن الطلبات غير المتزامنة والمتزامنة مع يُرجى الاطّلاع على خدمات Google Play والحالات التي تستخدم فيها كل منها في Tasks API.

يمكنك أيضًا بث الرسائل إلى جميع العُقد المتصلة. لاسترداد جميع العُقد المتصلة التي يمكنك إرسال الرسائل إليها، يجب تنفيذ الرمز التالي:

Kotlin

private fun getNodes(): Collection<String> {
    return Tasks.await(Wearable.getNodeClient(context).connectedNodes).map { it.id }
}

Java

private Collection<String> getNodes() {
    HashSet <String>results = new HashSet<String>();
    List<Node> nodes =
        Tasks.await(Wearable.getNodeClient(context).getConnectedNodes());
    for (Node node : nodes.getNodes()) {
        results.add(node.getId());
    }
    return results;
}

استلام رسالة

ليتم إشعارك بالرسائل المُستلَمة، نفِّذ MessageClient.OnMessageReceivedListener واجهة لتقديم أداة معالجة لأحداث الرسائل. ثم قم بتسجيل المستمع مع addListener . يوضح المثال التالي كيف يمكنك تطبيق المستمع للتحقق من VOICE_TRANSCRIPTION_MESSAGE_PATH إذا كان هذا الشرط true، يُرجى بدء نشاط لمعالجة البيانات الصوتية.

Kotlin

fun onMessageReceived(messageEvent: MessageEvent) {
    if (messageEvent.path == VOICE_TRANSCRIPTION_MESSAGE_PATH) {
        val startIntent = Intent(this, MainActivity::class.java).apply {
            addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
            putExtra("VOICE_DATA", messageEvent.data)
        }
        startActivity(this, startIntent)
    }
}

Java

@Override
public void onMessageReceived(MessageEvent messageEvent) {
    if (messageEvent.getPath().equals(VOICE_TRANSCRIPTION_MESSAGE_PATH)) {
        Intent startIntent = new Intent(this, MainActivity.class);
        startIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        startIntent.putExtra("VOICE_DATA", messageEvent.getData());
        startActivity(this, startIntent);
    }
}

يتطلّب هذا الرمز مزيدًا من تفاصيل التنفيذ. معلومات عن طريقة استخدام خدمة المستمعين الكاملة أو نشاطهم ضمن المنصة الاطلاع على أحداث طبقة البيانات