Мост

Мост — единственный выход приложения из песочницы. Объект window.pairx появляется до первого скрипта страницы; его нельзя подменить.

try {
  const { id } = await pairx.call("user.get");
} catch (error) {
  console.log(error.code, error.message);   // "unsupported", "offline", …
}
const off = pairx.on("storage.changed", ({ changes }) => { /* … */ });
off();

Имя метода — сегменты через точку, каждый начинается со строчной латинской буквы: ui.mainButton, storage.write. Неизвестный метод отклоняется с кодом unsupported; проверить заранее — app.supports.

Методы#

app.ready#

Интерфейс готов: Pairx убирает заставку. Вызывайте сразу, как нарисован первый экран.

Результат: true

app.close#

Закрыть приложение.

Результат: true

app.supports#

Есть ли метод в этой версии Pairx — для возможностей, которые появляются позже.

Результат: boolean

if (await pairx.call('app.supports', { name: 'share.toChat' })) { /* … */ }

user.get#

Кто открыл приложение. id — человек внутри этого приложения: в другом приложении у него другой ID; по нему нельзя узнать аккаунт Pairx.

Результат: { id: string, locale: string }

const { id } = await pairx.call('user.get');

context.get#

Где открыто приложение: общий экземпляр в чате, личный контекст или предпросмотр автора перед отправкой.

Результат: { kind: "chat" | "personal" | "preview", preview: boolean }

ui.theme#

Тема Pairx: светлая или тёмная и её цвета. CSS prefers-color-scheme в приложении следует той же теме.

Результат: { scheme: "light" | "dark", colors: { accent, background, surface, text, muted } }

ui.safeArea#

Отступы от краёв, которые не закрывает Pairx (шапку и нативную кнопку Pairx рисует сам, их отступы уже учтены).

Результат: { top, bottom, left, right }

ui.mainButton#

Нативная кнопка Pairx внизу экрана. Нажатие приходит событием ui.mainButton.clicked.

Результат: true

await pairx.call('ui.mainButton', { text: 'Отправить', visible: true });
pairx.on('ui.mainButton.clicked', send);

ui.backButton#

«Назад» в шапке Pairx вместо «Закрыть» — для своих экранов приложения; нажатие приходит событием ui.backButton.clicked.

Результат: true

ui.popup#

Нативное окно; в заголовке Pairx пишет название приложения и «код пользователя», чтобы окно нельзя было выдать за окно Pairx. До трёх кнопок; ответ — id нажатой.

Результат: string

const choice = await pairx.call('ui.popup', {
  message: 'Удалить запись?',
  buttons: [{ id: 'no', text: 'Отмена', type: 'cancel' }, { id: 'yes', text: 'Удалить', type: 'destructive' }],
});

ui.toast#

Короткая подсказка внизу экрана.

Результат: true

storage.snapshot#

Всё состояние общих данных на одном seq — см. «Общие данные».

Результат: { seq: number, private: object, stores: { [name]: Store } }

storage.write#

Одна запись в общее хранилище; операции — в справочнике хранилища. Изменение приходит всем участникам, и автору тоже, событием storage.changed на своём месте в порядке; обычно автору — до ответа на вызов, но полагаться на это нельзя.

Результат: { seq: number, … }

await pairx.call('storage.write', { op: 'log.append', store: 'queue', value: 'join' });

storage.private.set#

Личные данные человека. Обычно не вызывается напрямую: это делает localStorage.

Результат: { ok: true }

clipboard.writeText#

Скопировать текст, до 10 000 символов; только по нажатию человека.

Результат: true

diagnostics.error#

Сообщить об ошибке приложения. Сейчас Pairx принимает вызов и никуда его не отправляет; отчёты для автора придут позже, без данных хранилища.

Результат: true

События#

Ошибки#

Ошибка вызова — Error с полем code:

Параметры запуска#

pairx.launch есть сразу, без вызова:

Токен запуска#

pairx.launch.token — JWT, который Pairx подписывает при каждом открытии ключом Ed25519. Он нужен, когда у приложения появится свой сервер: сервер проверяет подпись по открытым ключам Pairx и узнаёт, кто и где открыл приложение, без общих секретов. Само приложение токену доверять не должно — внутри песочницы его можно только передать.

Алгоритм EdDSA, издатель pairx-apps, срок — 60 минут. Открытые ключи — https://api.pairx.org/.well-known/pairx-apps-keys.json (JWKS; ключ выбирается по kid из заголовка токена).

Будет позже#

Методы, которые появятся в следующих версиях моста. Проверяйте их через app.supports, а не по версии Pairx:

• ui.secondaryButton — Вторая нативная кнопка.
• share.toChat — Отправить приложение с параметром в другой чат.
• links.openApp — Открыть другое приложение Pairx.
• context.members — Участники чата (с разрешением chat.members).
• user.get → name — Имя человека (с разрешением profile.basic).