Carrot quest SDK

Тема

Инициализация ​

Результат шага

Приложение запускается без ошибок, в Logcat появляется "SDK init success" (либо ошибка в onFailure, по которой можно сразу диагностировать проблему).

Carrot.setup нужно вызывать один раз за жизненный цикл процесса — обычно в Application.onCreate(). Передавайте applicationContext и API Key из Подготовительных работ.

Метод для инициализации ​

kotlin
import io.carrotquest_sdk.android.Carrot

Carrot.setup(this, "API KEY", object : Carrot.Callback<Boolean> {
    override fun onResponse(result: Boolean) {
        if (result) println("SDK init success")
    }
    override fun onFailure(e: Throwable?) {
        println("SDK init error: ${e?.message}")
    }
})
java
import io.carrotquest_sdk.android.Carrot;

Carrot.setup(this, "API KEY", new Carrot.Callback<Boolean>() {
    @Override
    public void onResponse(Boolean result) {
        if (Boolean.TRUE.equals(result)) {
            System.out.println("SDK init success");
        }
    }
    @Override
    public void onFailure(Throwable e) {
        System.out.println("SDK init error: " + (e != null ? e.getMessage() : null));
    }
});

Параметры:

  • context — Android-контекст, лучше applicationContext;
  • apiKey — API Key из личного кабинета;
  • Callback<Boolean> — необязательный, но рекомендуемый: в onResponse(true) SDK сообщает об успешной инициализации, в onFailure — об ошибке (обычно это отсутствие сети или невалидный ключ). Существует и перегрузка setup(context, apiKey) без колбэка — её удобно использовать, когда ошибки уже отлавливаются другим способом.

Если в Logcat пришёл onFailure, проверьте сетевое соединение и правильность ключа (типичная ошибка — перепутать API Key и User Auth Key местами).

Логи и диагностика ​

По умолчанию уровень логирования — SdkLogLevel.NONE: SDK не пишет в логи ничего (в том числе в release-сборке). Чтобы включить подробные логи в Logcat на время отладки, задайте уровень:

kotlin
import io.carrotquest_sdk.android.core.logging.SdkLogLevel

Carrot.setLogLevel(SdkLogLevel.DEBUG)   // выключить: Carrot.setLogLevel(SdkLogLevel.NONE)
java
import io.carrotquest_sdk.android.core.logging.SdkLogLevel;

Carrot.setLogLevel(SdkLogLevel.DEBUG);  // выключить: Carrot.setLogLevel(SdkLogLevel.NONE);

Уровни накопительные: каждый следующий включает все более серьёзные (например, INFO выводит ещё и WARN с ERROR). От самого «тихого» к самому «подробному»:

УровеньЧто попадает в логКогда использовать
NONEничегоЗначение по умолчанию, для production. Логи выключены, накладных расходов нет.
ERRORтолько ошибки, ломающие работу (сбой сети, невалидный ключ, упавшая операция)Минимальный сигнал в production — например, чтобы пробросить только ошибки в свой крэш-репортер через setLogSink.
WARN+ предупреждения о нештатных, но восстановимых ситуациях (ретраи, переподключения, деградация)Когда нужно замечать «подозрительное», не утопая в потоке информационных сообщений.
INFO+ ключевые события жизненного цикла (инициализация, авторизация, подключение, приём пуша)Базовая отладка интеграции: понять, что и в каком порядке делает SDK, без лишнего шума.
DEBUG+ подробная диагностика (смена состояний, метаданные realtime-сообщений, принятые решения)Разбор конкретной проблемы интеграции — почему не пришёл пуш, не открылся чат, не отправилось сообщение.
VERBOSEвсё, максимально гранулярно (вплоть до отдельных событий/кадров)Глубокое расследование сложных/плавающих багов, когда нужен полный поток. Может быть очень многословным.

TIP

В production держите NONE (или ERROR, если хотите собирать ошибки в свой логгер). Уровни DEBUG / VERBOSE предназначены только для отладки — они многословны и могут содержать чувствительные данные (маскируются, см. setLogIncludeSensitive ниже).

Опционально можно получать записи логов прямо в своём коде (например, пробросить в свой логгер или крэш-репортер) и снять одномоментный срез состояния SDK для баг-репорта. Чувствительные значения (токены, e-mail, идентификаторы) маскируются, пока не вызван setLogIncludeSensitive(true):

kotlin
Carrot.setLogSink { entry -> myLogger.log(entry.category.toString() + " " + entry.message) }
// показать чувствительные значения полностью (только для локальной отладки):
Carrot.setLogIncludeSensitive(true)

val report = Carrot.getDiagnostics().toFormattedString()
java
Carrot.setLogSink(entry -> myLogger.log(entry.getCategory().toString() + " " + entry.getMessage()));
// показать чувствительные значения полностью (только для локальной отладки):
Carrot.setLogIncludeSensitive(true);

String report = Carrot.getDiagnostics().toFormattedString();

Авторизация пользователей ​

Если в приложении есть свой логин, передайте userId в Carrot quest, чтобы события и сообщения склеивались в одного пользователя. Способа два:

  • Carrot.auth(userId, userAuthKey, callback) — userAuthKey хранится в самом приложении. Простой вариант, подходит, если у вас нет бэкенда.
  • Carrot.hashedAuth(userId, hash, callback) — hash генерируется на вашем бэкенде. Безопасный вариант.

В обоих случаях колбэк имеет тип Callback<String> — в onResponse приходит userId авторизованного пользователя.

Важно

Вызывайте auth/hashedAuth внутри onResponse у setup. Если делать это раньше или параллельно, SDK успеет создать анонимного пользователя, и в кабинете появятся лишние записи без склейки.

Передача ID напрямую ​

kotlin
Carrot.setup(this, apiKey, object : Carrot.Callback<Boolean> {
    override fun onResponse(result: Boolean) {
        if (!result) return
        Carrot.auth(userId, userAuthKey, object : Carrot.Callback<String> {
            override fun onResponse(authedUserId: String?) {
                println("Carrot quest SDK auth ok, userId=$authedUserId")
            }
            override fun onFailure(e: Throwable?) {
                println("Carrot quest SDK auth error: ${e?.message}")
            }
        })
    }
    override fun onFailure(e: Throwable?) { /* setup failed */ }
})
java
Carrot.setup(this, apiKey, new Carrot.Callback<Boolean>() {
    @Override
    public void onResponse(Boolean result) {
        if (!Boolean.TRUE.equals(result)) return;
        Carrot.auth(userId, userAuthKey, new Carrot.Callback<String>() {
            @Override
            public void onResponse(String authedUserId) {
                System.out.println("Carrot quest SDK auth ok, userId=" + authedUserId);
            }
            @Override
            public void onFailure(Throwable e) {
                System.out.println("Carrot quest SDK auth error: " + (e != null ? e.getMessage() : null));
            }
        });
    }
    @Override
    public void onFailure(Throwable e) { /* setup failed */ }
});

Передача через hash ​

kotlin
Carrot.setup(this, apiKey, object : Carrot.Callback<Boolean> {
    override fun onResponse(result: Boolean) {
        if (!result) return
        Carrot.hashedAuth(userId, hash, object : Carrot.Callback<String> {
            override fun onResponse(authedUserId: String?) {
                println("Carrot quest SDK auth ok, userId=$authedUserId")
            }
            override fun onFailure(e: Throwable?) {
                println("Carrot quest SDK auth error: ${e?.message}")
            }
        })
    }
    override fun onFailure(e: Throwable?) { /* setup failed */ }
})
java
Carrot.setup(this, apiKey, new Carrot.Callback<Boolean>() {
    @Override
    public void onResponse(Boolean result) {
        if (!Boolean.TRUE.equals(result)) return;
        Carrot.hashedAuth(userId, hash, new Carrot.Callback<String>() {
            @Override
            public void onResponse(String authedUserId) {
                System.out.println("Carrot quest SDK auth ok, userId=" + authedUserId);
            }
            @Override
            public void onFailure(Throwable e) {
                System.out.println("Carrot quest SDK auth error: " + (e != null ? e.getMessage() : null));
            }
        });
    }
    @Override
    public void onFailure(Throwable e) { /* setup failed */ }
});