کاربرد تخصیص خودکار در دنیای واقعی #

به کمک پلتفرم ویرالینک میتوانید دستگاه های خود را به طور خودکار به مشتری های نهایی تخصیص دهید. فرض کنید شما به عنوان یک مدیر (یا توسعه دهنده) دستگاه های خود را مستقیم و یا به واسطه مراکز فروش، عرضه می نمایید. به کمک قابلیت تخصیص خودکار ویرالینک، مشتری های نهایی شما بعد از خرید و دسترسی فیزیکی به محصول شما می توانند بر اساس کد های دو بعدی (QR Code) و یا تکنیک های مشابه دستگاه های خود را در پلتفرم به خود اختصاص و مدیریت نمایند.

پس از اختصاص دستگاه به مشتری، مشتری مالک دستگاه شده و میتواند داده های دریافتی از دستگاه را مشاهده و یا خروجی دستگاه را کنترل نماید.

روش های تخصیص خودکار دستگاه #

یک کاربر میتواند با دانستن نام و کلید خصوصی (Secret key) دستگاه به آن دستگاه دسترسی پیدا کند. این کلید خصوصی که اختیاری می باشد، همیشه دارای زمان انقضاء است و ممکن است در طول زمان تغییر پیدا کند.

این کلید خصوصی به دو طریق قابل تهیه است:

• کلید سمت دستگاه (Device-side key) – دستگاه مد نظر دارای یک صفت سمت سرور به نام expirationTime می باشد که مشخص کننده زمان انقضا اعتبار کلید خصوصی در واحد timestamp است. ابتدا دستگاه درخواست تخصیص را به همراه داده های لازم به ویرالینک ارسال میکند سپس مشتری نهایی میتواند این دستگاه را به خود تخصیص دهد.
• کلید سمت سرور (Server-side key) – دستگاه مد نظر دارای یک صفت سمت سرور به نام claimingData می باشد که دارای محتوای کلید خصوصی و زمان انقضا می باشد. مشتری نهایی میتواند با در دست داشتن این محتوا دستگاه را به خود تخصیص دهد.

اختصاص خودکار توسط کلید Device-side  #

این فرآیند مستلزم ایجاد کلید توسط دستگاه بر اساس رخ دادن چند رویداد است. به عنوان مثال زمانیکه دستگاه روشن می شود و یا دکمه ای فیزیکی زده می شود. زمانیکه که کلید خصوصی ایجاد شد تنها برای مدت زمان مشخصی معتبر است. دستگاه این اطلاعات ( کلید خصوصی به همراه مدت زمان معتبر بودن کلید) را به پلتفرم ارسال میکند و پلتفرم این اطلاعات را خود ذخیره سازی می کند. 

دستگاه میتواند این اطلاعات را از طریق تمام پروتکل های پشتیبانی شده به پلتفرم ارسال نماید. این پیام میتواند دارای پارامتر های secretKey و durationMs می باشد که اختیاری است. پارامتر secretKey حاوی کلید خصوصی در فرآیند اختصاص خواهد بود و پارامتر durationMs مشخص کننده مدت زمان اعتبار آن در واحد میلی ثانیه است. در صورتی که پارامتر secretKey تعریف نشده باشد، متن خالی (empty string) به عنوان مقدار آن استفاده خواهد شد. در صورتی که durationMs تعریف نشده باشد مقدار پیشفرض device.claim.duration در جدول مقادیر پیشفرض است.

برای مستندات ارسال اطلاعات به پلتفرم نسبت با توجه به پروتکل ارتباطی به لینک های زیر مراجعه نمایید.

• MQTT Device API
• CoAP Device API
• HTTP Device API
• MQTT Gateway API

بعد از اینکه دستگاه اطلاعات حاوی کلید خصوصی و مدت زمان اعتبار آن را ارسال کرد، دستگاه بایستی این اطلاعات در اختیار کاربر نهایی قرار دهد (به عنوان مثال نمایش آن به واسطه کد های دو بعدی QR Code). کاربر با اسکن این کلید و با ارسال درخواست تخصیص ( حاوی کلید و نام دستگاه)، دستگاه مد نظر را به خود اختصاص می دهد. شما میتوانید یک فیلد منحصر به فرد مانند آدرس MAC را به عنوان نام دستگاه تعریف نمایید. در ادامه به نحوه ارسال درخواست خواهیم پرداخت.

توجه نمایید که گفته شد کلید خصوصی می تواند خالی باشد. پس در صورتی که دستگاه شما هیچ راهی برای نمایش کلید خصوصی نداشته باشد کاربر نهایی میتوانید با یک رویداد ( مثلا فشردن یک کلید خاص در دستگاه) و دانستن نام دستگاه (مثلا آدرس MAC) دستگاه، دستگاه را به خود اختصاص دهد. در همچنین مواقعی که کلید خصوصی ندارید به دلایل امنیتی بهتر است زمان اعتبار آن را بسیار کم (مثلا ۱ دقیقه) در نظر بگیرید.

مشتری نهایی میتواند درخواست تخصیص خود را با ابزارک طراحی شده (claiming widget) در داشبورد خود انجام دهد ( در ادامه به این ابزارک خواهیم پرداخت)

اختصاص خودکار توسط کلید Server-side #

فرض میکنیم شما به عنوان مدیر (یا توسعه دهنده) لیستی از آیدی ها ( و یا هر مقدار منحصر به فرد) دستگاه های خود را دارید. میتوان برای هر یک از دستگاه های خود یک کلید خصوصی رندم ایجاد و آن را در صفت سمت سرور دستگاه قرار دهید. اینکار را میتوانید از طریق رابط کاربری تحت وب و یا REST API انجام دهید. سپس شما میتوانید این کلید های خصوصی را به روش دلخواه خود (مثلا ارسال ایمیل و یا قراردادن آن در جعبه فروش دستگاه) به دست مشتری نهایی خود برسانید.

برای قرار دادن کلید خصوصی شما می توانید با ایجاد یک صفت سمت سرور در دستگاه مد نظر با نام “claimingData” و مقدار زیر انجام دهید.

{"secretKey": "YOUR_SECRET_KEY", "expirationTime": "1640995200000"}

مقدار expirationTime به صورت unix timestamp و در واحد میلی ثانیه است. مثال بالا تا تاریخ 2022/01/01 اعتبار دارد.

بعد از ایجاد کلید خصوصی در صفت سمت سرور کاربر میتواند از طریق ابزارک Claim widget دستگاه را به خود اختصاص دهد.

ابزارک Claim Widget  #

این ابزارک ساده به کاربر اجازه میدهد دستگاه خود را از طریق کلید خصوصی و نام دستگاه به خود اختصاص دهد.

• این ابزارک را میتوانید در دسته بندی ابزارک های ورودی Input Widgets پیدا کنید.
• میتوانید در پیکربندی این دستگاه فیلد کلید خصوصی را مخفی کنید
• میتوانید تمام پیام های موجود در این ابزارک را تغییر دهید.

API درخواست تخصیص دستگاه #

میتوان با ارسال دستور POST به لینک زیر درخواست تخصیص دستگاه نمود.

https://console.viralink.io/api/customer/device/$DEVICE_NAME/claim

فرمت داده پشتیبانی شده: 

{
  "secretKey":"value"
}

توجه نمایید که پیام حاوی پارامتر durationMs نخواهد بود و پارامتر secretKey اختیاری می باشد.

در صورتی که درخواست موفق آمیز باشد دستگاه به کاربر مدنظر اختصاص خواهد یافت.

API درخواست باز پس گیری (حذف) تخصیص دستگاه #

میتوان با ارسال دستور DELETE به لینک زیر درخواست تخصیص دستگاه نمود

https://console.viralink.io/api/customer/device/$DEVICE_NAME/claim

پاسخ دریافتی به شکل زیر خواهد بود:

{
  "result": {},
  "setOrExpired": true
}