نمای کلی Fence API

در Awareness API، مفهوم حصارها (fences) از geofencing گرفته شده است که در آن یک منطقه جغرافیایی یا geofence تعریف می‌شود و یک برنامه هنگامی که کاربر وارد یا از منطقه geofence خارج می‌شود، فراخوانی‌های برگشتی دریافت می‌کند. Fence API مفهوم geofencing را گسترش می‌دهد تا علاوه بر نزدیکی جغرافیایی، بسیاری از شرایط زمینه‌ای دیگر را نیز در بر بگیرد. یک برنامه هر زمان که وضعیت زمینه تغییر می‌کند، فراخوانی‌های برگشتی دریافت می‌کند. به عنوان مثال، اگر برنامه شما یک حصار برای هدفون تعریف کند، هنگامی که هدفون وصل است و هنگامی که از برق کشیده می‌شود، فراخوانی‌های برگشتی دریافت می‌کند.

شما می‌توانید از Fence API برای تعریف حصارها بر اساس سیگنال‌های زمینه‌ای، مانند موارد زیر، استفاده کنید:

• موقعیت مکانی فعلی کاربر (طول/عرض جغرافیایی)
• فعالیت فعلی کاربر، مانند پیاده‌روی یا رانندگی.
• شرایط خاص دستگاه، مانند اینکه آیا هدفون‌ها به برق وصل هستند یا خیر.
• نزدیکی به چراغ‌های راهنمای اطراف

رابط برنامه‌نویسی کاربردی Fence به شما امکان می‌دهد چندین سیگنال زمینه را برای ایجاد حصارها با عملگرهای منطقی AND ، OR و NOT ترکیب کنید. سپس برنامه شما هر زمان که شرایط حصار برآورده شود، فراخوانی‌های برگشتی دریافت می‌کند. برخی از نمونه‌های حصارهای ممکن عبارتند از:

• کاربر هدفون را به گوشش می‌زند و شروع به راه رفتن می‌کند.
• کاربر قبل از ساعت ۵ بعد از ظهر در یک روز کاری، یک محدوده جغرافیایی ۱۰۰ متری را وارد می‌کند.
• کاربر محدوده یک بیکن BLE خاص را وارد می‌کند.

مثال زیر نحوه تعریف یک حصار (fencer) را نشان می‌دهد که هر زمان کاربر راه می‌رود فعال می‌شود:

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

پس از تعریف حصار، باید موارد زیر را انجام دهید:

• برای ثبت حصار جهت دریافت فراخوانی‌های برگشتی، تابع updateFences فراخوانی کنید.
• یک تابع فراخوانی تعریف کنید که هنگام تغییر وضعیت حصار (fencer) فراخوانی شود.

مثال زیر متدی را نشان می‌دهد که یک حصار (fencer) ایجاد و ثبت می‌کند. در این مثال، از یک زیرکلاس سفارشی از BroadcastReceiver برای مدیریت intent هنگام فعال شدن حصار استفاده می‌شود.

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);
        }
    }
}