Вступ

Остання основна версія HelpCrunch Android SDK – v3.

Якщо ви зараз використовуєте SDK v2 для свого застосунку Android, важливо перейти на SDK v3, щоб ваша програма мала доступ до всіх найновіших можливостей.

Зауважте, що підтримку HelpCrunch Android SDK 1.0 і 2.0 припинено. Рекомендуємо якомога швидше перейти на версію 3.x.x.

Загальна інформація про міграцію

• Репозиторій Maven змінено, щоб уникнути конфліктів під час оновлень.
• Нова версія HelpCrunch SDK не сумісна з попередніми версіями. У ній є різні пакети моделей User, Options, Themes і Callback та пов’язаних з ними методів.
• HCTheme та пов’язані з ним класи мають деякі нові та застарілі методи.
• Для наступних методів більше не потрібен контекст або applicationContext: HelpCrunch.initialize, HelpCrunch.showChatScreen.
• HelpCrunch.showChatScreen тепер потребує більше часу для ініціалізації, тому тепер у нього є зворотний виклик.
• Нова версія має іншу структуру файлу strings.xml локалізації.

Відмінності між версією 2.x і новішим SDK

Версія 3

SDK v3 – це остання основна версія нашого Android SDK. Усі майбутні розробки API будуть базуватися на цій версії.

Версія 2

SDK v2 має API на основі v2. Розробка API припинений і не буде підтримуватися далі.

Нові можливості v3:

• Новий дизайн
• Кастомізація чату
• Краще відстеження івентів користувачів
• Краще відстеження івентів SDK (відкритий/закритий екран SDK, надходження нового повідомлення, перше надіслане повідомлення, перехід за посиланням) і статусу SDK
• Списки чатів і нова функція створення чатів
• Ручні і цільові чат-розсилки
• Оцінка чату
• Offline-повідомлення

Міграція

Нові пакети

Версія 3.x

//Core
import com.helpcrunch.library.core.Callback;
import com.helpcrunch.library.core.HelpCrunch;
import com.helpcrunch.library.core.options.HCOptions;
import com.helpcrunch.library.core.options.HCPreChatForm;

//UserData
import com.helpcrunch.library.core.models.user.HCUser;

//Theme
import com.helpcrunch.library.core.options.design.HCAvatarTheme;
import com.helpcrunch.library.core.options.design.HCChatAreaTheme;
import com.helpcrunch.library.core.options.design.HCMessageAreaTheme;
import com.helpcrunch.library.core.options.design.HCNotificationsTheme;
import com.helpcrunch.library.core.options.design.HCPreChatTheme;
import com.helpcrunch.library.core.options.design.HCSystemAlertsTheme;
import com.helpcrunch.library.core.options.design.HCTheme;
import com.helpcrunch.library.core.options.design.HCToolbarAreaTheme;

Версія 2.x

//Core
import com.helpcrunch.library.core.Callback;
import com.helpcrunch.library.core.HelpCrunch;
import com.helpcrunch.library.options.HCOptions;
import com.helpcrunch.library.options.HCPreChatForm;

//User
import com.helpcrunch.library.core.repository.models.user.HCUser;

//Theme
import com.helpcrunch.library.options.design.HCAvatarTheme;
import com.helpcrunch.library.options.design.HCChatAreaTheme;
import com.helpcrunch.library.options.design.HCMessageAreaTheme;
import com.helpcrunch.library.options.design.HCNotificationsTheme;
import com.helpcrunch.library.options.design.HCPreChatTheme;
import com.helpcrunch.library.options.design.HCSystemAlertsTheme;
import com.helpcrunch.library.options.design.HCTheme;
import com.helpcrunch.library.options.design.HCToolbarAreaTheme;

Ініціалізація

Версія 3.x

public static void initialize(@NotNull String organisation, int appId, @NotNull String secret, @Nullable HCUser user, @NotNull HCOptions options, @Nullable Callback<Object> callback)

Версія 2.x

public static void initialize(@NotNull Application application, @NotNull String organisation, int appId, @NotNull String secret, @Nullable HCUser user, @NotNull HCOptions options, @Nullable Callback<Object> callback)

Відкрийте екран чату

Версія 3.x

Оскільки ініціалізація SDK тепер займає більше часу, може виникнути ситуація, коли користувач спробує відкрити чат до завершення ініціалізації.

В цьому немає нічого страшного, але для зручності ми додали зворотний виклик, який відстежує статус відкриття чату.

public static void showChatScreen(@NotNull HCOptions options, @Nullable Callback<Object> callback)

Версія 2.x

public static void showChatScreen(@NotNull Context context, @NotNull HCOptions options)

Локалізація

Version 3.x

У зв'язку з появою деяких нових функцій додано нові ключі локалізації.

    <!--Chat Form-->
    <string name="hc_waiting_message">Searching for a free agent. \nPlease hold on.</string>
    <string name="hc_offline_message">Sorry, we\'re offline now 🙈 Feel free to send all your questions, contact details or feedback right here, and we\'ll get back to you asap 😇</string>

    <!--Chat messages menu-->
    <string name="hc_menu_copy">Copy</string>
    <string name="hc_menu_edit">Edit</string>
    <string name="hc_menu_copy_link">Copy link</string>
    <string name="hc_menu_open">Open</string>
    <string name="hc_menu_view_image">View image</string>
    <string name="hc_menu_item_file">File</string>
    <string name="hc_menu_item_photo">Photo</string>
    <string name="hc_download">Download</string>
    <string name="hc_share">Share…</string>
    <string name="hc_menu_end_chat">End this chat</string>

    <!--Chats list-->
    <string name="hc_support_team">%s Team</string>
    <string name="hc_no_chats_found_title">You have no chats</string>
    <string name="hc_no_chats_found_subtitle">Start a new one</string>
    <string name="hc_create_conversation_button">New conversation</string>

    <!--Chat-->
    <string name="hc_message_reply">"Reply"</string>
    <string name="hc_attachment_video">Video</string>
    <string name="hc_attachment_file">File</string>
    <string name="hc_attachment_image">Image</string>
    <string name="hc_attachment_location">Location</string>
    <string name="hc_attachment_article">Article</string>
    <string name="hc_message_hint">Type message</string>

    <plurals name="hc_typing">
        <item quantity="zero">typing…</item>
        <item quantity="one">is typing…</item>
        <item quantity="two">are typing…</item>
        <item quantity="few">are typing…</item>
        <item quantity="many">are typing…</item>
        <item quantity="other">are typing…</item>
    </plurals>

    <string name="hc_download_file_title">Download file?</string>
    <string name="hc_download_ok">Yes</string>
    <string name="hc_download_no">No</string>
    <string name="hc_download_loading_complete">Loading is complete 👌\nSaved to Downloads folder👌</string>
    <string name="hc_sharing_error">Unable to share file</string>
    <string name="hc_loading">Loading…</string>

    <string name="hc_copied">Copied</string>
    <string name="hc_sent_at">at</string>
    <string name="hc_permissions_ok">OK</string>
    <string name="hc_permissions_cancel">Cancel</string>
    <string name="hc_permissions_content">Allow file system and camera access to improve file sharing</string>
    <string name="hc_messages_updating">Updating…</string>
    <string name="hc_button_send">Send</string>
    <string name="hc_more_agents">and %d more</string>
    <string name="hc_new_chat_arrived">New chat has arrived</string>

    <!--Tech-->
    <string name="hc_you">You</string>
    <string name="hc_someone">Someone</string>
    <string name="hc_tech_client">client</string>
    <string name="hc_tech_chat_rated_poor">Poor</string>
    <string name="hc_tech_chat_rated_average">Average</string>
    <string name="hc_tech_chat_rated_great">Great</string>
    <string name="hc_tech_chat_rating_sent">Please rate this chat</string>
    <string name="hc_tech_chat_rating_sent_push">Please rate this chat</string>
    <string name="hc_tech_chat_rated">Chat rated %s</string>
    <string name="hc_tech_chat_marked_by">Chat marked %1$s by %2$s</string>
    <string name="hc_tech_chat_marked_as">Chat marked %s</string>
    <string name="hc_tech_someone_closed_chat">%s closed this chat</string>
    <string name="hc_closed">Closed</string>
    <string name="hc_chat_closed">This chat is closed</string>

    <string-array name="hc_chat_statuses">
        <item>New</item>
        <item>Open</item>
        <item>Pending</item>
        <item>On-hold</item>
        <item>Closed</item>
    </string-array>

    <!--Notifications-->
    <string name="hc_notification_channel_text">Allow Support messages notifications</string>

    <!--Pre-Chat Form-->
    <string name="hc_pre_chat_message">Usually we respond immediately. If not, you can expect a reply within a few hours. Please kindly introduce yourself.</string>
    <string name="hc_pre_chat_continue">Continue</string>
    <string name="hc_pre_chat_name">Name</string>
    <string name="hc_pre_chat_email">Email</string>
    <string name="hc_pre_chat_company">Company</string>
    <string name="hc_pre_chat_phone_number">Phone number</string>
    <string name="hc_pre_chat_error_required">%s is required</string>
    <string name="hc_pre_chat_error_pattern">%s is not valid</string>
    <string name="hc_pre_chat_gdpr">I have read and accept the %s</string>
    <string name="hc_pre_chat_gdpr_link_text">Privacy Policy</string>
    <string name="hc_department_picker_hint">Choose a department</string>
    <string name="hc_department_picker_any_department">Any department</string>

    <!--In App Errors -->
    <string name="hc_error_no_internet_connection">Please, check your internet connection</string>
    <string name="hc_error_handler_unknown">Something went wrong. Please try again later</string>
    <string name="hc_error_chat_deleted">This chat was removed by agent. You\'ll be logged out</string>
    <string name="hc_error_file_size">You can\'t send files bigger than 16 MB.</string>
    <string name="hc_error_file_cant_open">Can\'t open this file</string>
    <string name="hc_error_no_camera_exists">No Application exists for camera!</string>

    <!--File Picker-->
    <string name="hc_permission_file_picker_rationale">Storage permission is needed to access files.</string>
    <string name="hc_no_files_found">No files found</string>
    <string name="hc_attachments_title_text" formatted="false" translatable="false">(%d/%d)</string>
    <string name="hc_attachments_num" formatted="false" translatable="false">%d</string>
    <string name="hc_picker_title">Select an option</string>
    <string name="hc_select_photo_text">Select a media</string>
    <string name="hc_select_doc_text">Select a document</string>
    <string name="hc_videos">Videos</string>
    <string name="hc_images">Images</string>
    <string name="hc_all_photos">All Photos</string>
    <string name="hc_all_videos">All Videos</string>
    <string name="hc_all_files">All Files</string>
    <string name="hc_done">Done</string>
    <string name="hc_downloading">Downloading…</string>
    <string name="hc_debug">Debug</string>
    <string name="hc_send_intent_title">Send to:</string>

    <!--Rating View-->
    <string name="hc_rating_title">How do you rate your customer service experience?</string>
    <string name="hc_chat_rating_values_poor">Poor</string>
    <string name="hc_chat_rating_values_average">Average</string>
    <string name="hc_chat_rating_values_great">Great</string>
    <string name="hc_view_article">View article</string>
    <string name="hc_rating_title_block">Did this answer your question?</string>

    <!--End chat-->
    <string name="hc_end_chat_dialog_message">You will not be able to continue this conversation.</string>
    <string name="hc_end_chat_dialog_title">Are you sure?</string>
    <string name="hc_end_chat_dialog_ok">End chat</string>
    <string name="hc_end_chat_dialog_cancel">Cancel</string>

    <!--Knowledge Base-->
    <string name="hckb_written_by">Written by %s</string>
    <string name="hckb_updated_at">Updated %s</string>
    <string name="hckb_error_cant_open_article">Can\'t open the article</string>
    <string name="hckb_hide_articles">Hide articles</string>
    <string name="hckb_categories_title">Hello 👋 How can we help?</string>
    <string name="hckb_action_search_articles_hint">Search articles</string>
    <string name="hckb_no_articles_title">There are no articles</string>
    <string name="hckb_no_articles_subtitle">We’re working on adding our help articles.\nYou’ll find them here very soon.</string>

    <string name="hc_type_chat">Ask</string>
    <string name="hc_type_kb">Search</string>
    <string name="hc_draft_message">Draft:</string>
    <string name="notifications_you">You</string>

    <plurals name="hckb_see_all_articles_count">
        <item quantity="one">See %d more article</item>
        <item quantity="other">See all %d articles</item>
    </plurals>

    <plurals name="hckb_search_result">
        <item quantity="one">%d result</item>
        <item quantity="other">%d results</item>
    </plurals>

    <!--Time-->
    <string name="hc_time_today">Today</string>
    <string name="hc_time_yesterday">Yesterday</string>
    <string name="hc_time_just_now">&lt;1M</string>
    <string name="hc_time_mins_ago">M</string>
    <string name="hc_time_hours_ago">H</string>
    <string name="hc_time_days_ago">D</string>
    <string name="hc_time_week_ago">W</string>
    <string name="hc_error_wrong_email">Enter an email</string>
    <string name="hc_error_wrong_url">Enter a URL</string>
    <string name="hc_error_wrong_phone">Enter a phone number</string>
    <string name="hc_error_wrong_credit_card">Enter a credit card</string>
    <string name="hc_bot_answer_yes">Yes</string>
    <string name="hc_bot_answer_no">No</string>

    <string-array name="hc_month">
        <item>January</item>
        <item>February</item>
        <item>March</item>
        <item>April</item>
        <item>May</item>
        <item>June</item>
        <item>July</item>
        <item>August</item>
        <item>September</item>
        <item>October</item>
        <item>November</item>
        <item>December</item>
    </string-array>

Версія 2.x

	<!--Chat  Form-->
	<string name="hc_waiting_message">Searching for a free agent. Please hold on.</string>
	<string name="hc_message_hint">Type message</string>
	<string name="hc_select_image">Select image</string>
	<string name="hc_copied">Copied</string>
	<string name="hc_menu_copy">Copy</string>
	<string name="hc_menu_open">Open</string>
	<string name="hc_today">Today</string>
	<string name="hc_yesterday">Yesterday</string>
	<string name="hc_sent_at">at</string>
	<string name="hc_permissions_ok">OK</string>
	<string name="hc_permissions_cancel">Cancel</string>
	<string name="hc_permissions_content">Allow file system and camera access to improve file sharing</string>
	<string name="hc_messages_updating">Updating…</string>
	<string name="hc_button_send">Send</string>
	<string name="hc_more_agents">and %d more</string>
	<string name="hc_menu_view_image">View image</string>

	<plurals name="hc_typing">
		<item quantity="zero">typing…</item>
		<item quantity="one">is typing…</item>
		<item quantity="two">are typing…</item>
		<item quantity="few">are typing…</item>
		<item quantity="many">are typing…</item>
		<item quantity="other">are typing…</item>
	</plurals>

	<!--Notifications-->
	<string name="hc_default_notification_title">Help Crunch</string>
	<string name="hc_notification_channel_text">Allow messages notifications</string>

	<!--Pre-Chat Form-->
	<string name="hc_pre_chat_message">Usually we respond immediately. If not, you can expect a reply within a few hours. Please kindly introduce yourself.</string>
	<string name="hc_button_continue">Continue</string>
	<string name="hc_pre_chat_name">Name</string>
	<string name="hc_pre_chat_email">Email</string>
	<string name="hc_pre_chat_company">Company</string>
	<string name="hc_pre_chat_phone_number">Phone number</string>
	<string name="hc_required_error">%s is required</string>
	<string name="hc_pattern_error">%s does not valid</string>

	<!-- In App Errors -->
	<string name="hc_no_internet_connection_error">Please, check your internet connection</string>
	<string name="hc_handler_server_error">Server error. Repeat the request after 5 seconds</string>
	<string name="hc_handler_unknown_error">Something went wrong. Please try again later</string>
	<string name="hc_chat_deleted_error">This chat was removed by agent. You\'ll be logged out</string>
	<string name="hc_file_size_error">You can\'t send files bigger than 16 MB.</string>
	<string name="hc_file_cant_open_error">Can\'t open this file</string>
	<string name="hc_image_load_error">Can\'t load image</string>

	<!--File Picker-->
	<string name="hc_permission_file_picker_rationale">Storage permission is needed to access files.</string>
	<string name="hc_no_files_found">No files found</string>
	<string name="hc_attachments_title_text" formatted="false">(%d/%d)</string>
	<string name="hc_attachments_num" formatted="false">%d</string>
	<string name="hc_picker_title">Select an option</string>
	<string name="hc_select_photo_text">Select a media</string>
	<string name="hc_select_doc_text">Select a document</string>
	<string name="hc_no_camera_exists">No Application exists for camera!</string>
	<string name="hc_videos">Videos</string>
	<string name="hc_images">Images</string>
	<string name="hc_all_photos">All Photos</string>
	<string name="hc_all_videos">All Videos</string>
	<string name="hc_all_files">All Files</string>
	<string name="hc_done">Done</string>
	<string name="hc_menu_item_photo">Photo</string>
	<string name="hc_download">Download</string>
	<string name="hc_downloading">Downloading…</string>
	<string name="hc_downloaded">Downloaded</string>
	<string name="hc_menu_item_file">File</string>
	<string name="hc_share">Share…</string>
	<string name="hc_send_intent_title">Send to:</string>

Відстежування стану SDK

У версії 3.x тепер є можливість відстежувати стан SDK. Це робиться за допомогою класу BroadcastReceiver. Застосуйте новий IntentFilter(HelpCrunch.STATE), щоб використовувати цю функцію.

Усі доступні стани містяться в перелічуваному класі HelpCrunch.State. Наразі клас містить такі значення:

• IDLE - SDK очікує виклику ініціалізації
• READY - SDK готовий
• LOADING - SDK ініціалізується
• ERROR_BLOCKED_USER - користувача було заблоковано або видалено
  
• ERROR_INITIALIZATION - сталася помилка під час ініціалізації SDK, рекомендується перевірити підключення до мережі та дійсність даних для ініціалізації.
  
• ERROR_UNKNOWN - сталася помилка, але неможливо визначити її причину.
  

  private BroadcastReceiver hcStateBroadcastReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            HelpCrunch.State state = (HelpCrunch.State) intent.getSerializableExtra(HelpCrunch.STATE_TYPE);

           if (state != null) {
                Log.d("HcState", state.name());
            }
        }
    };

registerReceiver(hcStateBroadcastReceiver, new IntentFilter(HelpCrunch.STATE));

Ви можете в будь-який момент перевірити статус SDK за допомогою методу HelpCrunch.getState().

Кастомізація чату

У новому SDK v3.x типи HCTheme були перенесені в окремий клас перерахування під назвою HCTheme.Type. Це призводить до таких змін:

Версія 3.x

new HCTheme.Builder(HCTheme.Type.DEFAULT)
//or
new HCTheme.Builder(HCTheme.Type.DARK)
//or you can use Builder with custom color and shouldPaintIconsAutomatically flag
new HCTheme.Builder(R.color.main_color, true)

Deprecated методи

HCSystemAlertsTheme

HCChatAreaTheme

HCMessageAreaTheme

Версія 2.x

new HCTheme.Builder(HCTheme.DEFAULT)
//or
new HCTheme.Builder(HCTheme.DARK)
//or you can use Builder with custom color and shouldPaintIconsAutomatically flag
new HCTheme.Builder(R.color.main_color, true)

Завантаження зображення

Якщо ви раніше налаштовували підтримку файлів SVG за допомогою генерації API glide, ви можете видалити цей код із нових версій. Відтепер зображення SVG підтримуються за замовчуванням.

На завершення

Я сподіваюся, що міграція пройде легко та успішно. У будь-якому випадку, ми завжди допоможемо вам у нашому чаті підтримки 💪