Потік API, що відстежується

Автентифікований відстежуваний потік

Скористайтеся цим посібником, коли людина знаходить трекований об’єкт, проходить сценарій секретного доступу, входить у систему, а потім хоче виконати повніший сценарій володіння або зупинки на основі нотатки, не втрачаючи простішого варіанта прямого звіту.

Дотримуйтеся послідовності Основні документи API Анонімний потік Посилання на помилку

Коли використовувати цей потік

Це найкращий потік для людей, яким потрібна довготривала власність, коментарі, які можна редагувати, конвертація приміток, можливість модерування або можливість повертатися пізніше та керувати тим, що вони опублікували. Людина може почати з секретного коду або QR-токена перед входом, але після автентифікації їй не потрібно повторно надсилати код доступу під час кожного запису.

Крок 1: Вирішіть знайдений елемент

Короткий вебмаршрут входу завжди має вигляд /trackable/{code}. Клієнти API також можуть напряму розпізнавати цей токен.

POST https://www.locationnotes.com/api/trackables/lookup
Content-Type: application/json

{
  "code": "LN4C8R2Z"
}

{
  "found": true,
  "trackableId": "f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31",
  "isPublicCodeMatch": false,
  "usesSecretAccess": true,
  "redirectUrl": "/en-US/trackables/active/f3a8f841-20db-4f1e-a3f8-9f14bc0b3c31"
}

Якщо usesSecretAccess має значення true, браузер тепер має активний секретний сеанс для цього відстежуваного. Цей сеанс відокремлений від входу й існує спеціально для того, щоб користувач міг спочатку рухатися через робочий процес, який можна відстежувати.

Крок 2: Прочитайте корисне навантаження активного сеансу

GET https://www.locationnotes.com/api/trackables/active/{trackableId}

Це повідомляє клієнту, чи все ще потрібна активація, чи належить елемент до групи та які контексти активації доступні після входу.

Крок 3: Увійдіть і активуйте за потреби

Якщо елемент все ще неактивований, увійдіть і активуйте його особистому власнику або команді.

POST https://www.locationnotes.com/api/trackables/{trackableId}/activate
Authorization: Bearer <access token>
Content-Type: application/json

{
  "name": "",
  "description": "",
  "statusMessage": "",
  "useGroupDefaultTitle": true,
  "useGroupDefaultDescription": true,
  "useGroupDefaultStatusMessage": true,
  "teamId": null,
  "externalLinkUrl": "",
  "externalLinkDescription": "",
  "useGroupDefaultExternalLink": true,
  "initialJourneyStopLatitude": 47.6205,
  "initialJourneyStopLongitude": -122.3493
}

Якщо елемент походить із групи, активація також підтверджує його остаточну ідентичність на рівні елемента. Клієнти можуть або надіслати явні значення name, description і statusMessage, або залишити їх порожніми та використовувати useGroupDefaultTitle, useGroupDefaultDescription і useGroupDefaultStatusMessage, щоб зберегти поточні типові значення групи на активованому елементі.

Клієнти можуть додатково передавати <code>initialJourneyStopLatitude</code> і <code>initialJourneyStopLongitude</code>, коли під час активації потрібно одразу створити першу відстежену локацію.

Крок 4: Виберіть між простими та розширеними шляхами реєстрації

Після автентифікації клієнт все ще може використовувати легкий шлях прямого звіту або розширений шлях нотаток. Ці два шляхи доповнюють один одного, а не виключають один одного.

Простий шлях: створіть пряму зупинку в дорозі за допомогою POST /api/trackables/{trackableId}/journey-stops.
Повніший шлях: спочатку створіть нотатку, а потім прикріпіть трекований об’єкт до нотатки через POST /api/public/notes/{noteId}/trackables.
Шлях конверсії лише на веб-сайті: користувач, який увійшов у систему, може пізніше перетворити свою власну зупинку, пов’язану лише з місцезнаходженням, на нотатку, не дублюючи сегмент маршруту.

Крок 5A: Збережіть зупинку прямої подорожі

POST https://www.locationnotes.com/api/trackables/{trackableId}/journey-stops
Authorization: Bearer <access token>
Content-Type: application/json

{
  "latitude": 41.8819,
  "longitude": -87.6278
}

Збережена зупинка є незмінним знімком логістики. Якщо пов’язана нотатка згодом переміщується, подорож зберігає вихідну прив’язану координату, тому історія маршруту не змінюється миттєво.

Крок 5B: Створіть нотатку та додайте відстежуваний

POST https://www.locationnotes.com/api/notes/mine
Authorization: Bearer <access token>
Content-Type: application/json

{
  "categoryId": "4de6bb76-f25d-4c73-b8e3-81b9ca3bf08f",
  "title": "North lobby handoff",
  "body": "Visible as a note and as a trackable stop.",
  "latitude": 41.8818,
  "longitude": -87.6231,
  "visibility": "Private"
}

POST https://www.locationnotes.com/api/public/notes/{noteId}/trackables
Authorization: Bearer <access token>
Content-Type: application/json

{
  "trackableSecretCodes": "LN4C8R2Z"
}

Прикріплення трекованого об’єкта під час збереження нотатки також фіксує в цей момент знімок зупинки маршруту. Саме ця зупинка на основі нотатки захищає маршрут трекованого об’єкта, якщо власна точка нотатки на мапі пізніше зміниться.

Прикріплення нотатки також надає цьому трекованому об’єкту обов’язковий обсяг доступу до нотатки. Зупинка зберігає історію місця, але доступ до нотатки все одно визначається її власною видимістю та правилами обсягу доступу.

Крок 6: Коментуйте як автентифікований користувач

POST https://www.locationnotes.com/api/trackables/{trackableId}/comments
Authorization: Bearer <access token>
Content-Type: application/json

{
  "body": "Picked up and moving again."
}

Відстежувані коментарі, які ввійшли в обліковий запис, може редагувати лише автор коментаря, який увійшов у систему. Власники та поточні адміністратори команди можуть видаляти коментарі чи зупинки подорожі, але вони все одно не можуть переписати чужі слова.

Крок 7: Прочитайте повний маршрут і коментарі

GET https://www.locationnotes.com/api/trackables/{trackableId}/journey
GET https://www.locationnotes.com/api/trackables/{trackableId}/comments

Корисне навантаження подорожі вже впорядковано в хронологічному порядку та попередньо завантажено для візуалізації карти. Якщо зупинка виникла з приватної нотатки, яку програма перегляду не може відкрити, API все одно може відкрити точку розташування, опустивши захищений вміст нотатки.

Читання маршруту показують збережену зупинку разом із currentNotesAtCoordinate. Ця колекція є поточною моделлю читання видимих нотаток для тієї самої координати, а не доказом того, що зупинка назавжди володіє однією нотаткою.

Операційні примітки

Якщо користувач, який увійшов у систему, хоче використовувати простий потік на карті, дозвольте йому скористатися ним. Автентифікація має усунути перешкоди, а не змушувати інший інтерфейс користувача.
Експорти користувачів і команд тепер містять зупинки маршруту трекованих об’єктів, історію зупинок на основі нотаток і коментарі до трекованих об’єктів.
Видалення одного облікового запису не призводить до автоматичного видалення всього відстежуваного, якщо інші люди чи команда все ще покладаються на його історію.

Пов’язані посилання: Що таке трекер?, анонімний відстежуваний потік, і довідник помилок трекера.