Skip to content

api.md

Latest commit

 

History

History
190 lines (126 loc) · 8.79 KB

api.md

File metadata and controls

190 lines (126 loc) · 8.79 KB

API

Сеть

Для получения данных из банка по сети есть стандартизированный async Fetch API.

Есть собственный неглобальный декоратор fetch API fetchJson, который за вас может сделать:

  • serialize/parse json,

  • залогировать request/response через console.debug().

TODO: описать наше отношение к персональным данным и необходимость зачищать ненужные разработчику плагина поля, привести примеры работы sanitize().

Логирование

Для логирования есть знакомый всем стандартизированный Console API.

Все вызовы console на мобильных устройствах превращаются в текст лога. Вместе с текстом, как и везде, можно передавать структуры данных любой глубины.

Например,

console.log("что-то тут не так", {deadBodies: 999});

напишет в лог работы плагина

[log] что-то тут не так {deadBodies: 999}

Логи с мобильных устройств пользователи отправляют в случае, если что-то пошло не так (например, плагин выбросил ошибку), или специально (если поведение плагина некорректное, в настройках плагина есть кнопочка "отправить лог последней синхронизации".

console.assert(condition, ...args) ведёт себя везде так, как в node.js (бросает AssertionError если значение condition ложно) во всех окружениях, так что можно его смело использовать для строгих утверждений.

Вызов

console.assert(response.status === 200, "Не удалось получить транзакции", {response});

прервёт выполнение и пользователь на UI увидит

`Не удалось получить транзакции {response: { status: ... } }

Ошибки

Для того, чтобы прервать выполнение, достаточно выбросить любое исключение.

throw new Error("Всё не так =[");

Также есть возможность подсказать мобильному приложению, как обрабатывать ошибку, используя ZenMoney.Error как конструктор ошибки:

ZenMoney.Error(message: String?, logIsNotImportant: Bool?, forcePluginReinstall: Bool?)

Мы пока можем представить два юзкейса, когда это может понадобиться:

  1. Ошибка временная (сеть пропала, уборщица уронила сервер банка) и мы явно об этом знаем, и ничего не можем с этим поделать (пробовали делать retry), и просто не хотим, чтобы пользователь слал нам такие ошибки.

    В таком случае мы используем:

    throw new ZenMoney.Error("ДОКОЛЕ!", true /*logIsNotImportant*/, false);

    и на UI у пользователя не показывается кнопка "Отправить лог разработчикам"

  2. Настройки пользователя неверны (логин/пароль неверный) и мы не видим смысла запускать плагин еще раз с теми же самыми настройками.

    В таком случае мы используем:

    throw new ZenMoney.Error("Поправь настройки: неверные учетные данные!", false, /* forcePluginReinstall*/ true);

    и на UI пользователь видит ошибку и перенаправляется в окно настроек.

Получение введённых пользователем настроек

ZenMoney.getPreferences() возвращает введённые пользователем настройки плагина.

Ключами объекта являются значения key из preferences.xml

// При условии наличия в preferences.xml:
// <EditTextPreference key="login" ... />
// <EditTextPreference key="password" ... />
// Получаем так:
const {login, password} = ZenMoney.getPreferences();

Получение текстового ввода от пользователя в момент работы плагина

Например, для аутентификации понадобился SMS код, который банк прислал владельцу аккаунта.

Async API

const smsCode = await ZenMoney.readLine("Введите код из СМС сообщения");
if (!smsCode) {
    throw new Error("Без SMS-кода не смогу =[");
}

(deprecated) Sync API

ZenMoney.retrieveCode(message, imageUrl, options: {time, inputType})

options.time: Int? - время, через которое ввод станет неактуальным и окно закроется, вернув null.

options.inputType: ('text' | 'textPassword' | 'number' | 'numberDecimal' | 'numberPassword' | 'phone' | 'textEmailAddress')? - тип текстового ввода. Набор значений тот же, что и у EditTextPreference в preferences.xml.

const smsCode = ZenMoney.retrieveCode("Введите код из СМС сообщения");
if (!smsCode) {
    throw new Error("Без SMS-кода не смогу =[");
}

Функция ZenMoney.retrieveCode в браузерном отладчике реализована не очень хорошо: она читает значение файла zp_pipe.txt в папке плагина до тех пор, пока файл пустой.

После каждого использования этой функции рекомендуется опустошить файл zp_pipe.txt, иначе retrieveCode будет возвращать устаревший пользовательский ввод.

Когда-нибудь мы заменим этот костыль на браузерный confirm

Сохранение данных между вызовами плагина

Иногда может понадобиться сохранение данных между несколькими вызовами плагина. Примером таких данных может быть accessToken банка, выданный банком в ответ на успешное подтверждение выданного пользователю SMS-кода (мы же не хотим, чтобы при каждом запуске синхронизации пользователь вводил значение из SMS?).

ZenMoney.setData(key: String, value: Any?)

Удалить значение по ключу можно при помощи вызова ZenMoney.setData(key, null).

ZenMoney.getData(key: String, defaultValue: Any?) -> Any?

ZenMoney.clearData()

ZenMoney.saveData()

Физически данные сохраняются или очищаются только после вызова ZenMoney.saveData().

Оптимизация (уменьшение количества запросов)

ZenMoney.isAccountSkipped(id: String) -> Bool

Метод существует для того, чтобы не выполнять ненужную работу по выгрузке данных, которые решил пропустить пользователь.

Пропущенными счётами можно управлять в настройках подключения.

Необходимо его использовать для фильтрации полученных из банка счетов, до того как запрашивать по ним транзакции.

Документация по устаревшему API для не-modular плагинов

Можно найти здесь