اتصال ساده و ارسال پیام

در این مستند ما خواهیم دید که چگونه می‌توانید در Android به سرویس بلادرنگ بکتوری وصل شده، یا از آن قطع شوید و چگونه با ارسال پیام به کاربران دیگر یک چت ساده را شبیه‌سازی کنید.

پیش‌نیازها

  1. در صورتی که با سرویس بلادرنگ آشنایی ندارید، به معرفی سرویس بلادرنگ مراجعه کنید.
  2. در صورتی که هنوز با تنظیمات پنل سرویس بلادرنگ آشنا نشده اید، به تنظیمات پنل سرویس بلادرنگ مراجعه کنید.
  3. اگر هنوز SDK اندروید را راه‌اندازی نکرده‌اید، به راه‌اندازی SDK اندروید مراجعه کنید.

راه‌اندازی سرویس بلادرنگ

در ابتدا برای آن که بتوانید اعمال مربوط به سرویس بلادرنگ را به کمک SDK بکتوری انجام دهید، می‌بایست در قسمت راه‌اندازی SDK تابع setConnectivityKey را اضافه کنید:

// Extending android application to initialize backtory
public class MainApplication extends Application {
    @Override
    public void onCreate(){
        super.onCreate();
        BacktoryClient.init(KeyConfiguration.newBuilder().
            setAuthKeys("<X-Backtory-Authentication-Id>",
                        "<X-Backtory-Authentication-Key (Client)>").
            setConnectivityKey("<X-Backtory-Connectivity-Id>").
            build(), this);
    }
}

اتصال به سرویس بلادرنگ

اولین و ساده‌ترین کاری که باید برای استفاده از سرویس بلادرنگ در اپلیکیشن خود انجام دهید، برقراری ارتباط با سرور است. برای این کار کافیست کد زیر را زمانی که می‌خواهید کاربر اپلیکیشن شما آنلاین شود، انجام دهید:

// 1. Get Realtime api
BacktoryRealtimeAndroidApi backtoryApi = BacktoryRealtimeAndroidApi.getInstance();

// 2. Try to connect
backtoryApi.connectAsync(new BacktoryCallBack<ConnectResponse>() {
    @Override
    public void onResponse(BacktoryResponse<ConnectResponse> response) {
        // 3. Check if connected Successful
        if (response.isSuccessful()) {
            Log.d("TAG", "Connected: " + response.body().getUsername() + ":"
                    + response.body().getUserId());
        } else {
            Log.d("TAG", "Connect failed with code: " + response.code()
                    + " and message: " + response.message());
        }
    }
});

توجه: پیش از آن‌که بتوانید به سرویس بلادرنگ وصل شوید، حتما باید لاگین کرده باشید. در غیر این‌صورت، با خطا مواجه خواهید شد.

در صورتی که ()response.isSuccessful برابر true باشد، عملیات اتصال با موفقیت انجام شده است. این ارتباط تا زمانی که شما قطع ارتباط نکنید و یا مشکلی برای شبکه و اینترنت اپلیکیشن پیش نیاید، برقرار خواهد بود.

مهم: در صورتی که قبلا درخواست اتصال داده باشید و وصل بوده باشید، عملیات با خطا مواجه خواهد شد. همچنین وقتی که در حال وصل یا قطع شدن باشید، عبارت ()response.message بیانگر این خواهد بود که شما وسط عملیات دیگری هستید و نمی‌توانید درخواست جدید دهید. در مجموع شما حداکثر یک اتصال به بکتوری می‌توانید داشته باشید و نیازی به اتصالات بیشتر وجود ندارد.

ارسال پیام به یک کاربر

بعد از اتصال به بکتوری، ساده‌ترین نیازی که می‌توانید برآورده کنید، ارسال پیام مستقیم به کاربران دیگر است. شما می‌توانید حداکثر یک پیام ۸ کیلوبایتی برای یک کاربر دیگری ارسال کنید. برای اینکه بکتوری بفهمد مقصد پیام شما کدام کاربر است باید شناسه userId آن کاربر را بدانید. این شناسه می‌تواند از لیست دوستان شما از سرویس رایانش گرفته شود و یا شناسه کاربرانی که در رقابت آنلاین قبلی با هم بازی کردید و یا هر جای دیگری. با داشتن این شناسه به صورت زیر می‌توانید درخواست چت را ارسال کنید:

// 1. Get Realtime api
BacktoryRealtimeAndroidApi backtoryApi = BacktoryRealtimeAndroidApi.getInstance();

// 2. Send message to him/her
backtoryApi.sendChatToUserAsync("<User-Id-Here>", "Hello ali, what are you doing?",
        new BacktoryCallBack<Void>() {
            @Override
            public void onResponse(BacktoryResponse<Void> response) {
                // 3. Check if message is sent to server successfully
                if (response.isSuccessful()) {
                    Log.d("TAG", "Message is sent to Ali.");
                } else {
                    Log.d("TAG", "Failed to send message to ali with error: "
                            + response.message());
                }
            }
        });

بسیار مهم: شما وقتی پیامی برای کسی ارسال می‌کنید، علاوه بر اینکه پیام به کاربر مورد نظر شما می‌رسد، به تمامی گوشی‌ها و وسایل شما (از جمله دستگاه فعلی) هم که همین حساب کاربری بر روی آنهاست نیز، خواهد رسید. برای مثال اگر دیده باشید، در اپلیکیشن Hangouts گوگل، وقتی شما به دوست خود پیامی از طریق وب‌سایت ارسال کنید، آن پیام در لحظه در گوشی شما نیز نمایش داده خواهد شد.

شنود پیام‌های دریافتی (Listener)

در قسمت قبل، دیدیم که چگونه می‌توانید به یک کاربر پیام ارسال کنید. در حالت برعکس، باید بتوانید به صورت زنده (بلادرنگ) پیام‌هایی که کاربران دیگر برای شما ارسال کرده‌اند را دریافت کنید. برای این کار، باید یک Listener به SDK بدهید که در مواقع مختلف توسط SDK فراخوانی می‌شود و شما را از دریافت پیام‌های جدید خبردار می‌کند. این کار با کد زیر امکان‌پذیر است:

public class MainClass implements ChatListener, RealtimeSdkListener {

    public void init() {
        BacktoryRealtimeAndroidApi backtoryApi =
                BacktoryRealtimeAndroidApi.getInstance();

        // Set required listener
        backtoryApi.setRealtimeSdkListener(this);

        // Set chat listener
        backtoryApi.setChatListener(this);

        // Connect to backtory
        backtoryApi.connectAsync(new BacktoryCallBack<ConnectResponse>() {
            @Override
            public void onResponse(BacktoryResponse<ConnectResponse> response) {
                // Check if connected Successfully
                if (response.isSuccessful()) {
                    Log.d("TAG", "Connected: " + response.body().getUsername() + ":"
                            + response.body().getUserId());
                } else {
                    Log.d("TAG", "Connect failed with code: " + response.code()
                            + " and message: " + response.message());
                }
            }
        });
    }

    @Override
    public void onChatMessage(SimpleChatMessage simpleChatMessage) {
        String from = simpleChatMessage.getSenderId();
        String message = simpleChatMessage.getMessage();

        Log.d("TAG", "New message from, " + from + ":" + message);
    }

    /*********** Start Other Chat Listener Functions ************/
    @Override
    public void onPushMessage(SimpleChatMessage simpleChatMessage) {}
    @Override
    public void onGroupPushMessage(SimpleChatMessage simpleChatMessage) {}
    @Override
    public void onGroupChatMessage(SimpleChatMessage simpleChatMessage) {}
    @Override
    public void onChatInvitationMessage(ChatInvitationMessage chatInvitationMessage) {}
    @Override
    public void onChatGroupUserAddedMessage(UserAddedMessage userAddedMessage) {}
    @Override
    public void onChatGroupUserJoinedMessage(UserJoinedMessage userJoinedMessage) {}
    @Override
    public void onChatGroupUserLeftMessage(UserLeftMessage userLeftMessage) {}
    @Override
    public void onChatGroupUserRemovedMessage(UserRemovedMessage userRemovedMessage) {}
    /*********** End Chat Listener *************/

    /*********** Start Realtime Sdk Listener *************/
    @Override
    public void onDisconnect() {}
    @Override
    public void onException(ExceptionMessage exceptionMessage) {}
    /*********** End Realtime Sdk Listener *************/
}

در مثال بالا شلوغی کد به خاطر موارد اضافه‌ای است که ربطی به مثال ما نداشت، ولی به خاطر درست بودن کد آنها را آورده‌ایم. کل کاری که انجام شده عبارت‌اند از:

  1. کلاس خود را فرزند RealtimeSdkListener و ChatListener کردیم.
  2. تمام توابع این دو Listener را به صورت خالی پیاده‌سازی کردیم.
  3. در تابع init که خودمان نوشته‌ایم، SDK بکتوری را راه‌اندازی کردیم و مستقیما تابع connect را برای اتصال به سرور فراخوانی کردیم. تابع init را باید یک‌بار، هنگامی که می‌خواهید به سرویس بلادرنگ بکتوری وصل شوید، صدا بزنید.
  4. تابع onChatMessage را پیاده‌سازی کردیم که هر پیام دریافتی را log کند.

با همین چند قدم ما به سرویس بلادرنگ بکتوری متصل می‌شویم و هر زمان که کاربری برای ما پیامی ارسال کند، ما آن را log خواهیم کرد.

قطع ارتباط

اتصال به بکتوری، به علت اینکه یک ارتباط همیشگی وجود دارد، منابع گوشی را مصرف می‌کند و از طرفی برای حفظ اتصال، مکانیزم heartbeat وجود دارد، یعنی هر از چندی SDK پیام خالی برای سرور ارسال می‌کند تا سرور بتواند وضعیت آنلاین بودن دستگاه را بفهمد. بنابر این وقتی به این اتصال احتیاجی ندارید، باید آن را قطع کنید. برای قطع ارتباط کد ساده‌ای مانند حالت اتصال باید بنویسید:

// 1. Get Realtime api
BacktoryRealtimeAndroidApi backtoryApi = BacktoryRealtimeAndroidApi.getInstance();

// 2. Try to disconnect
backtoryApi.disconnectAsync(new BacktoryCallBack<Void>() {
    @Override
    public void onResponse(BacktoryResponse<Void> response) {
        // 3. Check if disconnect was successful
        if (response.isSuccessful()) {
            Log.d("TAG", "Disconnect successfully.");
        } else {
            Log.d("TAG", "Disconnect failed with code: " + response.code()
                    + " and message " + response.message());
        }
    }
});

مانند اتصال، برای قطع شدن هم ممکن است خطا رخ دهد. در صورتی که قبلا قطع شده‌اید و یا اصلا وصل نشده‌اید و یا اینکه قطع و یا وصل شدنی در حال اجرا باشد، شما پیام خطایی متناسب با این موارد دریافت خواهید کرد.

تشخیص قطعی ناخواسته

در برخی موارد مانند ضعیف بودن اینترنت، یا مشکل شبکه، اتصال به بکتوری ممکن است قطع شود. برای تشخیص این حالت می‌توانید از تابع onDisconnect در RealtimeSdkListener استفاده کنید که کاربرد آن را در کد زیر می‌توانید ببینید:

/*********** Start Realtime Sdk Listener *************/
@Override
public void onDisconnect()
{
    // Unexpected disconnect
    Log.d("TAG", "Disconnected Unexpectedly, "
            + "try to reconnect as soon as internet returns.");
}

@Override
public void onException(ExceptionMessage exceptionMessage) { }
/*********** End Realtime Sdk Listener *************/

همان‌طور که از روی متن log مشخص است، تابع onDisconnect زمانی فراخوانی می‌شود که ناخواسته از شبکه قطع شویم. دقت کنید که این تابع زمانی که شما تابع disconnect را صدا بزنید، فراخوانی نمی‌شود.

نکته‌ی مهم: در حال حاضر به دلیل محدودیت حافظه، سرویس بلادرنگ فقط چت‌های تا حداکثر ۱ ماه قبل را نگه می‌دارد و چت‌های قدیمی‌تر را بازیابی نمی‌کند.

در ادامه مستندات بلادرنگ، به سراغ گسترش قابلیت چت و ساخت گروه و امکاناتی شبیه به نرم‌افزار تلگرام خواهیم رفت.

گام بعدی