نظرة عامة على واجهة برمجة تطبيقات "Fence API"

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

يمكنك استخدام Fence API لتحديد الأسوار استنادًا إلى إشارات السياق، مثل ما يلي:

  • الموقع الجغرافي الحالي للمستخدم (خط العرض/خط الطول)
  • نشاط المستخدم الحالي، مثل المشي أو القيادة
  • الشروط الخاصة بالجهاز، مثل ما إذا كانت سماعات الرأس موصّلة
  • القرب من أجهزة البث القريبة

تتيح لك Fence API الجمع بين إشارات سياق متعددة لإنشاء أسوار باستخدام عوامل التشغيل المنطقية AND وOR وNOT. بعد ذلك، يتلقّى تطبيقك عمليات معاودة الاتصال كلما تم استيفاء شروط السياج. في ما يلي بعض الأمثلة على الأسوار المحتملة:

  • يقوم المستخدم بتوصيل سماعات الرأس ويبدأ المشي.
  • يدخل المستخدم إلى سياج جغرافي يبلغ طوله 100 متر قبل الساعة 5 مساءً في أحد أيام الأسبوع.
  • يدخل المستخدم إلى نطاق جهاز بث BLE معيّن.

يوضّح المثال التالي كيفية تحديد سياج يتم تفعيله كلما مشى المستخدم:

AwarenessFence walkingFence = DetectedActivityFence.during(DetectedActivityFence.WALKING);

بعد تحديد السياج، عليك إجراء ما يلي:

  • استدعاء updateFences لتسجيل السياج من أجل تلقّي عمليات معاودة الاتصال
  • تحديد عملية معاودة اتصال يمكن استدعاؤها عند تغيُّر حالة السياج

يوضّح المثال التالي طريقة تنشئ وتسجّل سياجًا. في هذا المثال، يتم استخدام فئة فرعية مخصّصة من BroadcastReceiver للتعامل مع الغرض عند تفعيل السياج.

Awareness.getFenceClient(this).updateFences(new FenceUpdateRequest.Builder()
    .addFence(FENCE_KEY, exercisingWithHeadphonesFence, mPendingIntent)
    .build())
    .addOnSuccessListener(new OnSuccessListener<Void>() {
        @Override
        public void onSuccess(Void aVoid) {
            Log.i(TAG, "Fence was successfully registered.");
        }
    })
    .addOnFailureListener(new OnFailureListener() {
        @Override
        public void onFailure(@NonNull Exception e) {
            Log.e(TAG, "Fence could not be registered: " + e);
        }
    });
public class FenceReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {

        FenceState fenceState = FenceState.extract(intent);

        if (TextUtils.equals(fenceState.getFenceKey(), FENCE_KEY)) {
            String fenceStateStr;
            switch (fenceState.getCurrentState()) {
                case FenceState.TRUE:
                    fenceStateStr = "true";
                    break;
                case FenceState.FALSE:
                    fenceStateStr = "false";
                    break;
                case FenceState.UNKNOWN:
                    fenceStateStr = "unknown";
                    break;
                default:
                    fenceStateStr = "unknown value";
            }
            mLogFragment.getLogView().println("Fence state: " + fenceStateStr);
        }
    }
}