نظرة عامة على واجهة برمجة تطبيقات "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);
        }
    }
}