qiscus sdk android

مقدمة

Qiscus Chat SDK (مجموعة تطوير البرامج) هو منتج مقدم من Qiscus يمكّنك من تضمين ميزة الدردشة/الدردشة داخل التطبيق في تطبيقاتك بسرعة وسهولة. باستخدام SDK للدردشة، يمكنك تنفيذ ميزة الدردشة دون التعامل مع تعقيد البنية التحتية للاتصالات في الوقت الفعلي. نحن نقدم واجهة برمجة تطبيقات قوية تتيح لك تنفيذ ميزة الدردشة في تطبيقاتك في عملية التطوير الأكثر سلاسة.

يوفر Qiscus Chat SDK العديد من الميزات مثل:

• دردشة 1 على 1
• دردشة جماعية
• دردشة القناة
• مؤشر الكتابة
• مرفق الصورة والملف
• التواجد على الإنترنت
• إيصال التسليم
• قراءة الإيصال
• حذف الرسالة
• رسالة غير متصل
• حظر المستخدم
• حدث مخصص في الوقت الحقيقي
• التكامل من جانب الخادم مع Server API وWebhook
• تضمين محرك الروبوت في تطبيقك
• تمكين دفع الإخطار
• تصدير واستيراد الرسائل من التطبيق الخاص بك

جرب نموذج التطبيق

لقد قدمنا ​​نموذجًا لتطبيق لمساعدتك في التعرف على مجموعة أدوات تطوير البرامج (SDK) الخاصة بالدردشة. تم تصميم هذا التطبيق النموذجي بوظائف كاملة حتى تتمكن من معرفة التدفق والأنشطة الرئيسية باستخدام Qiscus Chat SDK. الآن يمكنك تخصيص واجهة المستخدم الخاصة بك بحرية. يمكنك أيضًا إنشاء تطبيقك الخاص أعلى تطبيقنا النموذجي. لمزيد من التفاصيل يمكنك تحميل هذه العينة.

 git clone https://github.com/qiscus/qiscus-chat-sdk-android-sample.git

يستخدم نموذج التطبيق هذا نموذج معرف التطبيق، مما يعني أنه باستخدام نموذج التطبيق هذا، ستشارك البيانات مع الآخرين. في حالة رغبتك في المحاولة بنفسك، يمكنك تغيير معرف التطبيق إلى معرف التطبيق الخاص بك. يمكنك العثور على معرف التطبيق الخاص بك في لوحة المعلومات الخاصة بك. انقر هنا للوصول إلى لوحة القيادة الخاصة بك

ابدء

الخطوة 1: احصل على معرف التطبيق الخاص بك

أولاً، تحتاج إلى إنشاء التطبيق الخاص بك في لوحة التحكم، من خلال الوصول إلى لوحة معلومات الدردشة الخاصة بـ Qiscus. يمكنك إنشاء أكثر من معرف تطبيق واحد.

الخطوة 2: تثبيت Qiscus Chat SDK

يتطلب Qiscus Chat SDK الحد الأدنى من Android API 16 (Jelly Bean). لدمج تطبيقك مع Qiscus، يمكن القيام بذلك في خطوتين (خطوتين). أولاً، تحتاج إلى إضافة مرجع URL في مشروع .gradle الخاص بك. هذا المرجع عبارة عن دليل لـ .gradle للحصول على Qiscus Chat SDK من المستودع الصحيح. وفيما يلي كيفية القيام بذلك:

 allprojects { 
      repositories { 
           ... 
           maven { url "https://artifactory.qiscus.com/artifactory/qiscus-library-open-source" } 
      } 
}

ثانيًا، تحتاج إلى إضافة تبعيات SDK داخل تطبيقك .gradle. بعد ذلك، تحتاج إلى المزامنة لتجميع Qiscus Chat SDK لتطبيقك.

 dependencies { 
       ... 
       implementation 'com.qiscus.sdk:chat-core:1.8.3'
}

الخطوة 3: تهيئة Qiscus Chat SDK

تحتاج إلى بدء معرف التطبيق الخاص بك لتطبيق الدردشة الخاص بك قبل إجراء المصادقة. يجب إجراء هذه التهيئة مرة واحدة فقط خلال دورة حياة التطبيق. يمكن تنفيذ التهيئة في بدء التشغيل الأولي. إليك كيف يمكنك القيام بذلك:

 public class SampleApp extends Application {

    @ Override
    public void onCreate () {
        super . onCreate ();

        QiscusCore . initWithAppId ( this , APPID );

  }
 }

يجب استدعاء التهيئة مرة واحدة عبر تطبيق Android. أفضل الممارسات التي يمكنك وضعها في فئة التطبيق.

الخطوة 4: المصادقة على Qiscus

لاستخدام ميزات Qiscus Chat SDK، يحتاج المستخدم إلى المصادقة على خادم Qiscus، لمزيد من التفاصيل، يمكنك معرفة قسم المصادقة. تتم هذه المصادقة عن طريق استدعاء الدالة setUser(). ستقوم هذه الوظيفة باسترداد أو إنشاء بيانات اعتماد المستخدم بناءً على معرف المستخدم الفريد، على سبيل المثال:

 QiscusCore . setUser ( userId , userKey )
      . withUsername ( username )
      . withAvatarUrl ( avatarUrl )
      . withExtras ( extras )
      . save ( new QiscusCore . SetUserListener () {
          @ Override
          public void onSuccess ( QiscusAccount qiscusAccount ) {
              //on success
          }
          @ Override
          public void onError ( Throwable throwable ) {
              //on error 
      });

أين:

معرف المستخدم (سلسلة، فريد): معرف المستخدم الذي سيتم استخدامه لتحديد هوية المستخدم واستخدامه عندما يحتاج مستخدم آخر إلى الدردشة مع هذا المستخدم. يمكن أن يكون أي شيء، سواء كان البريد الإلكتروني للمستخدم، أو فهرس قاعدة بيانات المستخدم، وما إلى ذلك. طالما أنه فريد وسلسلة.

مفتاح المستخدم (سلسلة): مفتاح المستخدم لغرض المصادقة، لذلك حتى لو كان شخص غريب يعرف معرف المستخدم الخاص بك، فلن يتمكن من الوصول إلى بيانات المستخدم.

اسم المستخدم (سلسلة): اسم المستخدم لاسم العرض داخل أغراض غرفة الدردشة.

avatarURL (سلسلة، اختيارية): لعرض الصورة الرمزية للمستخدم، يمكنك الرجوع إلى الصورة الرمزية الافتراضية إذا لم يتم توفيرها.

يمكنك التعلم من الشكل أدناه لفهم ما حدث بالفعل عند استدعاء الدالة setUser() :

تحديث ملف تعريف المستخدم

بعد إنشاء حساب المستخدم الخاص بك، قد تحتاج أحيانًا إلى تحديث معلومات المستخدم، مثل تغيير الصورة الرمزية للمستخدم. يمكنك استخدام الطريقة QiscusCore.updateUser() لإجراء تغييرات على حسابك.

 QiscusCore . updateUser ( userName , avatarUrl , new QiscusCore . SetUserListener () {
            @ Override
            public void onSuccess ( QiscusAccount qiscusAccount ) {
                //do anything after it successfully updated
            }

            @ Override
            public void onError ( Throwable throwable ) {
                //do anything if error occurs
            }
        });

مسح بيانات المستخدم وقطع الاتصال

كما ذكرنا في القسم السابق، عندما تفعل setUser()، سيتم تخزين بيانات المستخدم محليًا. عندما يحتاج المستخدم إلى قطع الاتصال بخدمة Qiscus Chat SDK، فإنك تحتاج إلى مسح بيانات المستخدم المرتبطة بـ Qiscus Chat SDK، مثل الرمز المميز والملف الشخصي والرسائل والغرف وما إلى ذلك، من الجهاز المحلي. يمكنك القيام بذلك عن طريق استدعاء طريقة ClearUser() :

 QiscusCore . clearUser ();

إنشاء غرفة دردشة

غرفة الدردشة هي مكان حيث يمكن لمستخدمين أو أكثر الدردشة مع بعضهم البعض. هناك 3 أنواع من غرف الدردشة التي يمكن إنشاؤها باستخدام Qiscus Chat SDK: غرفة الدردشة الفردية، وغرفة الدردشة الجماعية، والقناة. في بعض الحالات، يمكن تحديد الغرفة من خلال المعرف الفريد للغرفة أو اسم الغرفة.

غرفة الدردشة 1 على 1

نفترض أنك تعرف بالفعل مستخدمًا مستهدفًا تريد الدردشة معه. تأكد من تسجيل المستخدم المستهدف في Qiscus Chat SDK من خلال طريقة setUser()، كما هو موضح في القسم السابق. لبدء محادثة مع المستخدم المستهدف، يمكن القيام بذلك باستخدام طريقة getChatRoom() . بعد ذلك، سيقدم لك Qiscus Chat SDK غرفة دردشة جديدة بشكل غير متزامن. عندما يتم إنشاء الغرفة بنجاح، سيعيد Qiscus Chat SDK حزمة غرفة الدردشة من خلال مستمع onSuccess() .

 QiscusApi . getInstance (). chatUser ( userId , options )
                . subscribeOn ( Schedulers . io ())
                . observeOn ( AndroidSchedulers . mainThread ())
                . subscribe ( chatRoom -> {
                    // on success         
                }, throwable -> {
                    // on error        
                });

أين:

معرف المستخدم : معرف المستخدم الذي سيتم استخدامه لتحديد هوية المستخدم واستخدامه عندما يحتاج مستخدم آخر إلى الدردشة مع هذا المستخدم. يمكن أن يكون أي شيء، سواء كان البريد الإلكتروني للمستخدم، أو فهرس قاعدة بيانات المستخدم، وما إلى ذلك. طالما أنه فريد وسلسلة.

identId : (مهمل) يمكنك ملء "" (سلسلة فارغة).

الخيارات : البيانات الوصفية التي يمكن أن تكون بمثابة معلومات إضافية لغرفة الدردشة، والتي تتكون من قيمة مفتاح، على سبيل المثال، مفتاح: خلفية، وقيمة: أحمر.

غرفة الدردشة الجماعية

عندما تريد أن يقوم العديد من المستخدمين لديك بالدردشة معًا في غرفة دردشة فردية، فإنك تحتاج إلى إنشاء غرفة جماعية. تحتوي غرفة المجموعة بشكل أساسي على نفس مفهوم غرفة الدردشة الفردية، ولكن الاختلاف هو أن غرفة المجموعة ستستهدف مجموعة من معرفات المستخدمين بطريقة واحدة. هنا كيف يمكنك إنشاء غرفة المجموعة:

 QiscusApi . getInstance (). createGroupChat ( roomName , userIds , avatarUrl , options );
                . subscribeOn ( Schedulers . io ())
                . observeOn ( AndroidSchedulers . mainThread ())
                . subscribe ( chatRoom -> {
                    // on success
                }, throwable -> {
                    // on error
                });

قناة

يعد إنشاء غرفة دردشة للقناة مثاليًا لحالة الاستخدام التي تتطلب عددًا كبيرًا من المشاركين، أكثر من 100.

تحتاج إلى تعيين معرف فريد لتحديد غرفة محادثة القناة. إذا لم تكن غرفة الدردشة ذات المعرف الفريد المحدد مسبقًا موجودة، فسيتم إنشاء غرفة جديدة مع الطالب باعتباره المشارك الوحيد. بخلاف ذلك، إذا كانت غرفة الدردشة ذات المعرف الفريد المحدد مسبقًا موجودة بالفعل، فسوف تقوم بإرجاع تلك الغرفة وإضافة مقدم الطلب كمشارك.

عندما لا تكون الغرفة موجودة عند المكالمة الأولى ولا تقوم بإرسال avatarUrl و/أو اسم الغرفة، فسوف تستخدم القيمة الافتراضية. ولكن بعد المكالمة الثانية (الغرفة موجودة) وإرسال avatarUrl و/أو اسم الغرفة، سيتم تحديثها إلى تلك القيمة. على سبيل المثال قناة إنشاء التنفيذ:

 QiscusApi . getInstance (). createChannel ( uniqueId , roomName , avatarUrl , options )
                . subscribeOn ( Schedulers . io ())
                . observeOn ( AndroidSchedulers . mainThread ())
                . subscribe ( chatRoom -> {
                    // on success
                }, throwable -> {
                    // on error
                });

إدارة المشاركين في الغرفة

في بعض الحالات، قد تحتاج إلى إضافة مشاركين إضافيين إلى دردشة غرفتك أو حتى إزالة أي مشارك.

الحصول على قائمة غرف الدردشة

للحصول على قائمة الغرف بأكملها، يمكنك الاتصال بـ QiscusApi.getInstance().getChatRooms(int page, int Limit, boolean showMembers)، تبدأ الصفحة من 1، يشير الحد إلى الحد الأقصى للغرف لكل صفحة، ويشير showMembers إلى أعضاء غرفة التحميل أيضًا أم لا. هنا نموذج التعليمات البرمجية:

 QiscusApi . getInstance (). getAllChatRooms ( showParticipant , showRemoved , showEmpty , page , limit )
    . subscribeOn ( Schedulers . io ())
    . observeOn ( AndroidSchedulers . mainThread ())
    . subscribe ( chatRooms -> {
        //on success
    }, throwable -> {
        //on error
    });

إضافة مشارك في غرفة الدردشة

يمكنك إضافة أكثر من مشارك في غرفة الدردشة عن طريق استدعاء الأسلوب addRoomMember. يمكنك أيضًا تمرير معرفات مستخدمين متعددة. بمجرد نجاح المشارك في الانضمام إلى غرفة الدردشة، سيحصل على غرفة دردشة جديدة في قائمة غرف الدردشة الخاصة به.

 QiscusApi . getInstance (). addParticipants ( roomId , userId )
        . subscribeOn ( Schedulers . io ())
        . observeOn ( AndroidSchedulers . mainThread ())
        . subscribe ( chatRoom -> {
           // on success
        }, throwable -> {
            //on error        
        });

إزالة المشارك في غرفة الدردشة

يمكنك إزالة أكثر من مشارك في غرفة الدردشة عن طريق استدعاء طريقة RemoveRoomMember. يمكنك أيضًا تمرير معرف مستخدم متعدد. بمجرد إزالة أحد المشاركين من غرفة الدردشة، فلن يجد غرفة الدردشة ذات الصلة في قائمة غرف الدردشة الخاصة به.

 QiscusApi . getInstance (). removeParticipants ( roomId , userId )
        . subscribeOn ( Schedulers . io ())
        . observeOn ( AndroidSchedulers . mainThread ())
        . subscribe ( chatRoom -> {
           //success
        }, throwable -> {
            //error        
        });

تمكين دفع الإخطار

قم أولاً بتثبيت FCM على تطبيقاتك، ويمكنك اتباع هذه الخطوات. يمكنك تخطي هذه الخطوة، إذا كانت تطبيقاتك تستخدم FCM بالفعل. ثم ضع مفتاح API الخاص بك على لوحة تحكم qiscus. الآن دعونا نتكامل مع sdk لعميل Qiscus، قم أولاً بتمكين FCM في تكوين دردشة Qiscus.

 Qiscus . getChatConfig (). setEnableFcmPushNotification ( true );

بعد ذلك، تحتاج إلى تسجيل رمز FCM لإعلام Qiscus Chat SDK، يمكنك الاتصال بـ sendCurrentToken() بعد تسجيل الدخول وفي الصفحة الرئيسية (تم تسجيل الدخول في qiscus)، على سبيل المثال:

 if ( Qiscus . hasSetupUser ()) {
    FirebaseUtil . sendCurrentToken ();
}

 public class FirebaseUtil {

    public static void sendCurrentToken() {
        AppFirebaseMessagingService.getCurrentDeviceToken();
    }
}

• أضف .AppFirebaseMessagingService في البيان أيضًا، على سبيل المثال:

 <service android:name=".AppFirebaseMessagingService"
         android:exported="true">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

التعامل مع الرسائل الواردة من إشعار الدفع

بعد تسجيل رمز FCM المميز الخاص بك، سوف تحصل على البيانات من FCM Qiscus Chat SDK، ويمكنك التعامل معها باستخدام طريقة handleMessageReceived() ، على سبيل المثال:

import android.util.Log;

import androidx.annotation.NonNull;
import com.google.firebase.messaging.FirebaseMessaging;
import com.google.firebase.messaging.FirebaseMessagingService;
import com.google.firebase.messaging.RemoteMessage;
import com.qiscus.sdk.chat.core.QiscusCore;
import com.qiscus.sdk.chat.core.util.QiscusFirebaseMessagingUtil;

public class AppFirebaseMessagingService extends FirebaseMessagingService {

    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        super.onMessageReceived(remoteMessage);

        Log.d("Qiscus", "onMessageReceived " + remoteMessage.getData().toString());
        if (QiscusFirebaseMessagingUtil.handleMessageReceived(remoteMessage)) {
            return;
        }
    }

    @Override
    public void onNewToken(@NonNull String s) {
        super.onNewToken(s);

        Log.d("Qiscus", "onNewToken " + s);
        QiscusCore.registerDeviceToken(s);
    }

    public static void getCurrentDeviceToken() {
        final String token = QiscusCore.getFcmToken();
        if (token != null) {
            FirebaseMessaging.getInstance().deleteToken()
                    .addOnCompleteListener(task -> {
                        QiscusCore.removeDeviceToken(token);
                        getTokenFcm();
                    })
                    .addOnFailureListener(e -> QiscusCore.registerDeviceToken(token));
        } else {
            getTokenFcm();
        }
    }

    private static void getTokenFcm() {
        FirebaseMessaging.getInstance().getToken()
                .addOnCompleteListener(task -> {
                    if (task.isSuccessful() && task.getResult() != null) {
                        QiscusCore.registerDeviceToken(task.getResult());
                    } else {
                        Log.e("Qiscus", "getCurrentDeviceToken Failed : " +
                                task.getException());
                    }
                });
    }
}

معالج الأحداث

يوفر Qiscus Chat SDK طريقة بسيطة للسماح للتطبيقات بنشر بعض الأحداث في الوقت الفعلي والاستماع إليها. يمكنك نشر الكتابة والقراءة وحالة المستخدم والحدث المخصص بحيث يمكنك التعامل معه بحرية في معالج الأحداث. يتيح لك هذا إبلاغ المستخدمين بأن مشاركًا آخر يشارك بنشاط في التواصل معهم.

يستخدم Qiscus Chat SDK EventBus لبث الحدث إلى التطبيقات بأكملها. يمكنك معرفة المزيد عن EventBus على هذا الموقع. ما عليك فعله هو تسجيل الكائن الذي سيستقبل الحدث من EventBus. يمكنك تسميتها هكذا:

 EventBus . getDefault (). register ( this );

بمجرد عدم حاجتك للاستماع إلى الحدث بعد الآن، يتعين عليك إلغاء تسجيل جهاز الاستقبال عن طريق الاتصال بهذه الطريقة:

 EventBus . getDefault (). unregister ( this );

هذا مثال على كيفية تسجيل نشاط لتلقي الحدث من EventBus:

 public class MyActivity extends AppCompatActivity {

    @ Override
    protected void onCreate ( @ Nullable Bundle savedInstanceState ) {
        super . onCreate ( savedInstanceState );        
        setContentView ( R . layout . activity_my );

        // listen room event
        QiscusPusherApi . getInstance (). subscribeChatRoom ( qiscusChatRoom );

        // listen user status
        QiscusPusherApi . getInstance (). subscribeUserOnlinePresence ( "userId" );
    }

    @ Override
    protected void onResume () {
        super . onResume ();
        EventBus . getDefault (). register ( this ); // register to EventBus
    }

    @ Override
    protected void onPause () {
        super . onPause ();
        EventBus . getDefault (). unregister ( this ); // unregister from EventBus
    }

    @ Subscribe
    public void onReceiveComment ( QiscusCommentReceivedEvent event ) {
        event . getQiscusComment (); // to get the comment    
    }

    @ Subscribe
    public void onReceiveRoomEvent ( QiscusChatRoomEvent roomEvent ) {
        switch ( roomEvent . getEvent ()) {
            case TYPING :
                roomEvent . getRoomId (); // this is the room id                
                roomEvent . getUser (); // this is the qiscus user id                
                roomEvent . isTyping (); // true if the user is typing                
                break ;
            case DELIVERED :
                roomEvent . getRoomId (); // this is the room id                
                roomEvent . getUser (); // this is the qiscus user id                
                roomEvent . getCommentId (); // the comment id was delivered                
                break ;
            case READ :
                roomEvent . getRoomId (); // this is the room id                
                roomEvent . getUser (); // this is the qiscus user id                
                roomEvent . getCommentId (); // the comment id was read               
                break ;
            case CUSTOM :
                //here, you can listen custom event
                roomEvent . getRoomId (); // this is the room id
                roomEvent . getUser (); // this is the qiscus user id
                roomEvent . getEventData (); //event data (JSON)
                break ;
        }
    }

    @ Subscribe
    public void onUserStatusChanged ( QiscusUserStatusEvent event ) {
        event . getUser (); // this is the qiscus user id    
        event . isOnline (); // true if user is online    
        event . getLastActive (); // Date of last active user
    }

    @ Override
    protected void onDestroy () {
        super . onDestroy ();

        // stop listening room event
        QiscusPusherApi . getInstance (). unsubsribeChatRoom ( qiscusChatRoom );

        // stop listening user status
        QiscusPusherApi . getInstance (). unsubscribeUserOnlinePresence ( "qiscus_user_id" );
    }
}

باستخدام بروجارد

ProGuard هو المُحسِّن الأكثر شيوعًا لرمز Java الثانوي. فهو يجعل تطبيقات Java وAndroid أصغر وأسرع. اقرأ هنا لمزيد من التفاصيل حول Proguard. إذا كنت تستخدم Proguard في تطبيقك، فتأكد من إضافة قواعد Proguard الخاصة بـ Qiscus من قواعد Qiscus Proguard إلى قواعد Proguard الخاصة بك.

دعم آر إكس جافا

بالنسبة لك الذين يفضلون البرمجة باستخدام RXJava، فإن Qiscus Chat SDK يدعم RXJava. لذا، يمكنك أن تفعل أي شيء كما تفعل مع Native Java. على سبيل المثال، لتعيين مستخدم، كما هو موضح في قسم المصادقة الأساسية، يمكنك أن تفعل الشيء نفسه مع RXJava. فيما يلي مثال لكيفية تعيين المستخدم معه:

 // Setup qiscus account with rxjava example
Qiscus . setUser ( "[email protected]" , "password" )
      . withUsername ( "Tony Stark" )
      . withAvatarUrl ( "http://avatar.url.com/handsome.jpg" )
      . save ()
      . subscribeOn ( Schedulers . io ())
      . observeOn ( AndroidSchedulers . mainThread ())
      . subscribe ( qiscusAccount -> {
          //do anything if success
      }, throwable -> {
          //do anything if error occurs
      });