Mobil SDK: xətalar, səbəbləri və həlli

Son yeniləmə: 13 oktyabr 2026 · 7 dəq oxunur

Addımlar

1. 1

   Açar və qoşulma xətaları

   • api_key səhvdir və ya bu platforma üçün deyil (server 401 invalid_api_key). Səbəb: açar səhv kopyalanıb, ləğv olunub, yenisi yaradılandan 7 gün keçib, ya da o biri platformanın açarıdır. Həll: Android-də android_…, iOS-da ios_… açarı; Quraşdırma bölməsində açarın əvvəlini müqayisə edin, lazımsa «Yeni açar».
   • Eyni xəta iOS-da açar düzgün olanda. Səbəb: kanalın «iOS Bundle ID»-si tətbiqin Bundle ID-sindən fərqlidir, iOS SDK onu hər qoşulmada göndərir. Bundle ID kanal yaradılanda sehrbazda yazılır, paneldə sonradan dəyişmək yeri yoxdur. Həll: Clomni AI-yə tətbiqin düzgün Bundle ID-sini yazın, Clomni komandası düzəldir.
   • call Clomni.initialize first. Səbəb: metod initialize-dən əvvəl çağırılıb. Həll: initialize-i açılışda çağırın, Android-də Application.onCreate-də, sinfi manifestdə android:name ilə.
   • initialize was called before; the first call stays. Həll: bir dəfə çağırın; açarı dəyişmək üçün tətbiqi yenidən başladın.
   • this App SDK inbox is switched off in Clomni. Səbəb: kanal hesabda söndürülüb və ya hesab aktiv deyil. Messenger açılmır. Həll: Clomni AI-yə yazın, yoxlayıb lazım olsa Clomni komandasına ötürəcək.
   • Şirkət şəbəkəsində qoşulmur. Səbəb: proxy və ya icazə siyahısı. Həll: app.clomni.ai-a HTTPS və WebSocket üçün icazə verin.
2. 2

   İstifadəçinin tanıdılması

   • user_hash səhvdir. identity_secret və user_id-ni yoxlayın (server 403 identity_verification_failed). Səbəb: hash uyğun gəlmir. Həll: hash loginUser-dəki ilə hərfbəhərf eyni user_id sətrindən, cari secret ilə, kiçik hərfli hex olmalıdır. userId verilmirsə, kənar boşluqları silinmiş, kiçik hərfli e-poçtdan. Təhlükəsizlik › «Hash-i yoxla» səbəbi deyir: «Uyğun gəlmir», «Hash böyük hərflərlədir», «Hash 64 simvollu hex olmalıdır».
   • Secret dəyişəndən sonra girişlər rədd olunur. Səbəb: «Yeni secret yarat»-dan sonra köhnə secret yalnız 7 gün işləyir. «Hash-i yoxla» «Düzdür, amma köhnə secret ilə hazırlanıb» deyirsə, server hələ köhnə secret-dədir. Həll: serveri yeni secret-ə keçirin.
   • «Məcburi» rejimdə hash-siz giriş rədd olunur. Həll: hash göndərin, ya da bütün tətbiq versiyaları göndərənə qədər «Tövsiyə olunan» rejimə qayıdın.
   • Telefonun növbəti istifadəçisi əvvəlkinin söhbətlərini görür. Səbəb: logout çağırılmır. Həll: Clomni.logout()-u tətbiqin öz çıxışı ilə çağırın.
   • Operator istifadəçinin adını görmür. Həll: loginUser-ə name və email verin, sonrakı dəyişikliklər üçün updateUser.
3. 3

   Push gəlmir

   Kanalın Push bölməsindəki «Test bildirişi» ilə başlayın: cavab FCM və ya APNs-in öz cavabıdır, mənası «Mobil SDK push açarları» məqaləsindədir.

   • iOS: BadEnvironmentKeyInToken. Səbəb: APNs açarı yalnız Sandbox və ya yalnız Production üçündür. Xcode-dan işləyir, TestFlight-dan yox (və ya əksinə). Həll: Apple Developer-də «Environment: Sandbox & Production» ilə yeni açar yaradıb yükləyin.
   • Cihaz «Test bildirişi» siyahısında yoxdur. Səbəb: token Clomni-yə çatmayıb. Həll: telefonda bildirişlərə icazə verin, setDeviceToken çağırışını yoxlayın, Messenger-i bir dəfə açın.
   • Android 13+: bildiriş yoxdur, logda notification not shown (POST_NOTIFICATIONS?). Həll: manifestdə POST_NOTIFICATIONS elan edin və icazəni istəyin. SDK onu özü istəmir.
   • Android: panelə google-services.json yüklənib. Panel «Faylda project_id yoxdur» deyir. Həll: Firebase › Project settings › Service accounts › «Generate new private key» faylını yükləyin.
   • Android: SENDER_ID_MISMATCH. Səbəb: service account başqa Firebase layihəsinindir. Həll: tətbiqin google-services.json-u ilə eyni layihənin service account-u.
   • Android: bildiriş yalnız tətbiq açıq olanda gəlir. Səbəb: data mesajı yalnız ekranda emal olunur. Həll: FirebaseMessagingService-də ClomniPush.handle; React Native-də setBackgroundMessageHandler index.js-də; Flutter-də onBackgroundMessage runApp-dan əvvəl; Unity-də öz ListenerService-iniz.
   • iOS: capability yoxdur. Səbəb: Push Notifications capability əlavə olunmayıb, token alınmır. Həll: Xcode › Signing & Capabilities › + Capability › Push Notifications.
   • iOS, React Native və ya Flutter: Clomni bildirişinə toxunanda yalnız tətbiq açılır, söhbət yox. Səbəb: Clomni iOS push-ları APNs-dən birbaşa gəlir, Firebase kitabxanası onları görmür. Həll: native UNUserNotificationCenterDelegate (ClomniNotifications) və APNs tokeni getAPNSToken ilə, platformanın məqaləsindəki kimi.
   • iOS: InvalidProviderToken (Key ID və ya Team ID səhvdir), DeviceTokenNotForTopic (Push-dakı Bundle ID tətbiqinki deyil).
   • iOS: bildirişə toxunanda «Call must be made on main thread» ilə çökür. Həll: delegate metodlarını @MainActor edin.
   • Android: ikon boz kvadratdır. Həll: setNotificationIcon ilə ağ siluet ikon.
   • Android: logda push token not registered: …. Səbəb: token serverə çatmayıb. Həll: şəbəkəni, setDeviceToken çağırışını və paneldəki service account JSON-u yoxlayın.
4. 4

   Quraşdırma (Android, iOS, React Native, Flutter, Unity)

   • Android build manifest birləşməsində dayanır: provider#androidx.core.content.FileProvider@authorities … collides with another value (məsələn, Unity-də unity-webview ilə). Səbəb: SDK 1.0.4 və əvvəlkilər androidx-in öz FileProvider sinfini elan edirdi, tətbiq və ya başqa kitabxana da onu elan edir. Həll: SDK-nı 1.0.5-ə yeniləyin (Unity: #unity-1.0.5, sonra EDM4U ilə resolve). Bu xətaya görə tools:replace əlavə etmisinizsə, silin.
   • pod install ClomniMessenger-i tapmır («Unable to find a specification»). Səbəb: SDK CocoaPods trunk-da yoxdur. Həll: pod 'ClomniMessenger', :git => 'https://github.com/clomni/clomni-mobile-sdk.git', :tag => '1.0.4'. Unity-də bu sətri hər iOS build-dən sonra build qovluğundakı Podfile-da dəyişin.
   • React Native: pod install «@clomni/react-native needs React Native 0.75 or later» deyir. Həll: React Native-i 0.75+ edin, ya da Podfile-a yuxarıdakı pod 'ClomniMessenger' sətrini əlavə edin.
   • React Native: link zamanı ClomniMessenger simvollarında xəta. Həll: Podfile-a eyni sətir və pod install.
   • React Native, Expo: «The package doesn't seem to be linked». Səbəb: Expo Go native modulu yükləmir. Həll: development build (npx expo prebuild, npx expo run:ios, EAS build).
   • Flutter: pod install «clomni_flutter: the iOS SDK is not on CocoaPods trunk» yazıb dayanır. Səbəb: Swift Package Manager söndürülüb və Podfile-da sətir yoxdur. Həll: flutter config --enable-swift-package-manager, ya da sətri target 'Runner' içinə yazın.
   • Flutter, Android: Messenger açılanda çökür, üzən düymə görünmür. Həll: MainActivity FlutterFragmentActivity-dən törəməlidir.
   • Unity: Editor-da heç nə olmur, bu normaldır. Xcode modulu tapmır: .xcworkspace-i açın.
5. 5

   Messenger, flow və dil

   • Messenger açılmır, logda heç nə yoxdur. Həll: debug log; Unity-də cihazda sınayın.
   • iOS: no window to present the messenger from yet. Həll: present-i ekran göstəriləndən sonra çağırın.
   • Messenger açılır, amma boş qalır və ya «Yenidən cəhd et» göstərir. Səbəb: ilk yükləmə alınmayıb: internet, app.clomni.ai bloklanıb, ya da açar rədd olunub. Həll: logda xətaya baxın.
   • Paneldəki dəyişiklik tətbiqdə görünmür. Səbəb: Görünüş qaralamadadır. Həll: Görünüş › «Dərc et».
   • startFlow heç nə etmir. Səbəb: hadisəyə bağlı dərc olunmuş flow yoxdur. Həll: flow qurucusunda trigger «Tətbiq hadisəsi», eyni ad, flow dərc olunub. Flow-lar bölməsində «Hadisə: …» adı görünməlidir.
   • startFlow-a flow-un adı verilib. Hadisənin adı flow-un adı deyil: Flow-lar bölməsində flow-un altındakı «Hadisə: …» sətrindəki adı verin. «Söhbət başlayanda» trigger-li flow startFlow ilə başlamır.
   • Yeni söhbət flow-u işləmir. Səbəb: sehrbazda seçilən flow qaralama kimi qalıb, «Ümumi baxış» «Yeni söhbət flow-u dərc olunmayıb» deyir. Həll: Flow-lar bölməsində dərc edin.
   • Flow mətnində {{data.…}} boş qalır. Həll: startFlow datasında və flow-da eyni açar adı.
   • Messenger gözlənilən dildə danışmır. Səbəb: setLanguage paneldə sönülü dili seçib, ya da dil seçilməyib və telefonun dili Messenger-də yoxdur. Həll: Görünüş › «Dillər»-də dili yandırıb dərc edin, ya da setLanguage("az").
   • Üzən düymə görünmür. Səbəb: həm paneldə, həm kodda sönülüdür. Həll: setLauncherVisible(true) və ya Görünüş › Tema › «Üzən düymə».
   • React Native: üzən düymə tətbiqin soyuq açılışında görünmür. Səbəb: SDK 1.0.1-in xətası, 1.0.2-də düzəlir. O vaxta qədər Messenger-i öz düymənizdən açın.
   • React Native, Android: tətbiq ikonla yenidən açılanda açıq Messenger itir. Səbəb: MainActivity singleTask-dır. SDK 1.0.2-də düzəlir.
   • Logda setTheme: primaryColor "…" is not #RRGGBB. Səbəb: rəngin formatı. Həll: # ilə altı hex rəqəm, məsələn #0A66C2.
   • iOS: font family "…" is not in the app; the system font stays. Səbəb: şrift bundle-da yoxdur. Həll: şrift faylını hədəfə və Info.plist-də UIAppFonts-a əlavə edin.
   • Agent tətbiqdən gələn söhbəti görmür. Həll: kanalın «Əməkdaşlar» bölməsinə əlavə edin.
   • «Ümumi baxış»: «… cihazda köhnə SDK versiyası işləyir». Həll: tətbiqi yeni SDK ilə buraxın.
6. 6

   Hələ alınmırsa

   Clomni AI-yə yazın: platforma və SDK versiyası (Kotlin və Swift-də Clomni.version), App ID, «Ümumi baxış»ın dedikləri, problem anındakı debug log, push üçün «Test bildirişi» cavabı. Heç vaxt Identity Secret, tam API açarı, .p8 və ya service account faylı göndərməyin.

7. 7

   Tam təlimat

   • PDF: Clomni Mobile SDK təlimatı, Azərbaycan, ingilis və rus dilində.
   • Onlayn: Problemlərin həlli.
   • Paneldə: kanalın ayarlar sütununda «Təlimat».