Mulai Cepat: Menambahkan obrolan ke aplikasi Anda

  • Artikel
  • 46 menit untuk membaca

Memulai dengan Azure Communication Services dengan menggunakan SDK Obrolan Communication Services untuk menambahkan obrolan real time ke aplikasi Anda. Dalam mulai cepat ini, kita akan menggunakan SDK Obrolan untuk membuat utas obrolan yang memungkinkan pengguna melakukan percakapan satu sama lain. Untuk mempelajari lebih lanjut tentang konsep Obrolan, kunjungi dokumentasi konseptual obrolan.

Prasyarat

Sebelum memulai, pastikan untuk:

  • Membuat akun Azure dengan langganan aktif. Untuk mengetahui detailnya, lihat Membuat akun secara gratis.

  • Menginstal Node.js versi LTS Aktif dan LTS Pemeliharaan.

  • Membuat sumber daya Azure Communication Services. Untuk detailnya, lihat Membuat sumber daya Azure Communication Services. Anda harus merekam titik akhir sumber daya dan string koneksi untuk mulai cepat ini.

  • Buat tiga Azure Communication Services Pengguna dan terbitkan Token Akses Pengguna. Pastikan untuk mengatur cakupan ke obrolan, dan catat string token serta string user_id. Demo lengkap membuat utas dengan dua peserta awal, kemudian menambahkan peserta ketiga ke utas. Anda juga dapat menggunakan Azure CLI dan menjalankan perintah di bawah ini dengan string koneksi Anda untuk membuat pengguna dan token akses.

    az communication identity issue-access-token --scope chat --connection-string "yourConnectionString"

    Untuk detailnya, lihat Menggunakan Azure CLI untuk Membuat dan Mengelola Token Akses.

Persiapan

Membuat aplikasi web baru

Pertama, buka terminal atau jendela perintah, buat direktori baru untuk aplikasi Anda, dan navigasikan ke sana.

mkdir chat-quickstart && cd chat-quickstart

Jalankan npm init -y untuk membuat file package.json dengan pengaturan default.

npm init -y

Menginstal paket

Gunakan perintah npm install untuk menginstal Communication Services SDK untuk JavaScript di bawah.

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

Opsi --save mencantumkan pustaka sebagai dependensi di file package.json Anda.

Siapkan kerangka kerja aplikasi

Mulai cepat ini menggunakan paket untuk menggabungkan aset aplikasi. Jalankan perintah berikut untuk menginstalnya dan mencantumkannya sebagai dependensi pengembangan di package.json Anda:

npm install parcel --save-dev

Buat file index.html di direktori akar proyek Anda. Kami akan menggunakan file ini sebagai templat untuk menambahkan kemampuan obrolan menggunakan Azure Communication Chat SDK untuk JavaScript.

<!DOCTYPE html>
<html>
  <head>
    <title>Communication Client - Chat Sample</title>
  </head>
  <body>
    <h4>Azure Communication Services</h4>
    <h1>Chat Quickstart</h1>
    <script src="./client.js" type="module"></script>
  </body>
</html>

Buat file di direktori akar proyek Anda yang disebut client.js agar berisi logika aplikasi untuk mulai cepat ini.

Membuat klien obrolan

Untuk membuat klien obrolan di aplikasi web, Anda akan menggunakan titik akhir Communications Service dan token akses yang dibuat sebagai bagian dari langkah prasyarat.

Token akses pengguna memungkinkan Anda membuat aplikasi klien yang langsung mengautentikasi ke Azure Communication Services. Mulai cepat ini tidak mencakup pembuatan tingkat layanan untuk mengelola token untuk aplikasi obrolan Anda. Lihat konsep obrolan untuk mengetahui informasi selengkapnya tentang arsitektur obrolan, dan token akses pengguna untuk mengetahui informasi selengkapnya tentang token akses.

Di client.js, gunakan titik akhir dan token akses dalam kode di bawah untuk menambahkan kemampuan obrolan menggunakan Azure Communication Chat SDK untuk JavaScript.


import { ChatClient } from '@azure/communication-chat';
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

// Your unique Azure Communication service endpoint
let endpointUrl = '<replace with your resource endpoint>';
// The user access token generated as part of the pre-requisites
let userAccessToken = '<USER_ACCESS_TOKEN>';

let chatClient = new ChatClient(endpointUrl, new AzureCommunicationTokenCredential(userAccessToken));
console.log('Azure Communication Chat client created!');

Jalankan kode

Jalankan perintah berikut untuk menjalankan aplikasi Anda:

npx parcel index.html

Buka browser Anda dan navigasi ke http://localhost:1234/. Di konsol alat developer di browser Anda, Anda akan melihat berikut:

Azure Communication Chat client created!

Model objek

Kelas dan tatap muka berikut menangani beberapa fitur utama SDK Obrolan Azure Communication Services untuk JavaScript.

Nama Deskripsi
ChatClient Kelas ini diperlukan untuk fungsionalitas Obrolan. Anda membuat contoh dari informasi langganan Anda, dan menggunakannya untuk membuat, mendapatkan, menghapus utas, dan berlangganan acara obrolan.
ChatThreadClient Kelas ini diperlukan untuk fungsionalitas Utas Obrolan. Anda mendapatkan instans melalui ChatClient dan menggunakannya untuk mengirim/menerima/memperbarui/menghapus pesan, menambah/menghapus/mendapatkan pengguna, mengirim pemberitahuan pengetikan dan tanda terima baca.

Memulai utas obrolan

Gunakan metode createThread untuk membuat utas obrolan.

createThreadRequest digunakan untuk mendeskripsikan permintaan utas:

  • Gunakan topic untuk memberikan topik pada obrolan ini. Topik dapat diperbarui setelah utas obrolan dibuat menggunakan fungsi UpdateThread.
  • Gunakan participants untuk mencantumkan peserta untuk ditambahkan ke utas obrolan.

Setelah diselesaikan, metode createChatThread menampilkan CreateChatThreadResult. Model ini berisi properti chatThread tempat Anda dapat mengakses id dari utas yang baru dibuat. Anda kemudian dapat menggunakan id untuk mendapatkan instans ChatThreadClient. Kemudian ChatThreadClient dapat digunakan untuk melakukan operasi dalam utas seperti mengirim pesan atau mencantumkan peserta.

async function createChatThread() {
  const createChatThreadRequest = {
    topic: "Hello, World!"
  };
  const createChatThreadOptions = {
    participants: [
      {
        id: { communicationUserId: '<USER_ID>' },
        displayName: '<USER_DISPLAY_NAME>'
      }
    ]
  };
  const createChatThreadResult = await chatClient.createChatThread(
    createChatThreadRequest,
    createChatThreadOptions
  );
  const threadId = createChatThreadResult.chatThread.id;
  return threadId;
}

createChatThread().then(async threadId => {
  console.log(`Thread created:${threadId}`);
  // PLACEHOLDERS
  // <CREATE CHAT THREAD CLIENT>
  // <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD>
  // <SEND MESSAGE TO A CHAT THREAD>
  // <LIST MESSAGES IN A CHAT THREAD>
  // <ADD NEW PARTICIPANT TO THREAD>
  // <LIST PARTICIPANTS IN A THREAD>
  // <REMOVE PARTICIPANT FROM THREAD>
  });

Saat me-refresh tab browser, Anda akan melihat hal berikut di konsol:

Thread created: <thread_id>

Mendapatkan klien utas obrolan

Metode getChatThreadClient menampilkan chatThreadClient untuk utas yang sudah ada. Ini dapat digunakan untuk melakukan operasi pada utas yang dibuat: menambahkan peserta, mengirim pesan, dll. threadId adalah ID unik dari utas obrolan yang ada.

let chatThreadClient = chatClient.getChatThreadClient(threadId);
console.log(`Chat Thread client for threadId:${threadId}`);

Tambahkan kode ini sebagai ganti komentar <CREATE CHAT THREAD CLIENT> di client.js, refresh tab browser Anda dan periksa konsol, Anda akan melihat:

Chat Thread client for threadId: <threadId>

Mencantumkan semua utas obrolan

Metode listChatThreads ini menampilkan PagedAsyncIterableIterator dari jenis ChatThreadItem. Ini dapat digunakan untuk mencantumkan semua utas obrolan. Iterator [ChatThreadItem] adalah respons yang ditampilkan dari mencantumkan utas

const threads = chatClient.listChatThreads();
for await (const thread of threads) {
   // your code here
}

Mengirim pesan ke utas obrolan

Gunakan sendMessage metode untuk mengirim pesan ke utas yang diidentifikasi oleh threadId.

sendMessageRequest digunakan untuk menjelaskan permintaan pesan:

  • Gunakan content untuk menyediakan konten pesan obrolan;

sendMessageOptions digunakan untuk menjelaskan param opsional operasi:

  • Gunakan senderDisplayName untuk menentukan nama tampilan pengirim;
  • Gunakan type untuk menentukan jenis pesan, seperti 'teks' atau 'html';
  • Gunakan metadata secara opsional untuk menyertakan data lain yang ingin Anda kirim bersama dengan pesan. Bidang ini menyediakan mekanisme bagi pengembang untuk memperluas fungsionalitas pesan obrolan dan menambahkan informasi kustom untuk kasus penggunaan Anda. Misalnya, saat berbagi tautan file dalam pesan, Anda mungkin ingin menambahkan 'hasAttachment: true' dalam metadata sehingga aplikasi penerima dapat mengurainya dan menampilkannya.

SendChatMessageResult adalah respons yang ditampilkan dari mengirim pesan, berisi ID, yang merupakan ID unik pesan.

const sendMessageRequest =
{
  content: 'Please take a look at the attachment'
};
let sendMessageOptions =
{
  senderDisplayName : 'Jack',
  type: 'text',
  metadata: {
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
  }
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;
console.log(`Message sent!, message id:${messageId}`);

Tambahkan kode ini sebagai ganti komentar <SEND MESSAGE TO A CHAT THREAD> di client.js, refresh tab browser Anda dan periksa konsol.

Message sent!, message id:<number>

Menerima pesan obrolan dari utas obrolan

Dengan sinyal real time, Anda dapat berlangganan untuk mendengarkan pesan masuk baru dan memperbarui pesan saat ini di memori. Azure Communication Services mendukung daftar peristiwa yang dapat Anda ikuti.

// open notifications channel
await chatClient.startRealtimeNotifications();
// subscribe to new notification
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // your code here
});

Tambahkan kode ini sebagai ganti komentar <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> di client.js. Refresh tab browser Anda, Anda akan melihat di konsol Notification chatMessageReceived pesan;

Atau, Anda dapat mengambil pesan obrolan dengan polling metode listMessages pada interval tertentu.


const messages = chatThreadClient.listMessages();
for await (const message of messages) {
   // your code here
}

Tambahkan kode ini sebagai ganti komentar <LIST MESSAGES IN A CHAT THREAD> di client.js. Refresh tab Anda, Anda harus menemukan daftar pesan yang dikirim dalam utas obrolan ini di konsol.

listMessages mengembalikan berbagai jenis pesan yang dapat diidentifikasi oleh chatMessage.type.

Untuk detail selengkapnya, lihat Jenis Pesan.

Menambahkan pengguna sebagai peserta ke utas obrolan

Setelah utas obrolan dibuat, Anda kemudian dapat menambahkan dan menghapus pengguna utas tersebut. Dengan menambahkan pengguna, Anda memberi mereka akses untuk mengirim pesan ke utas obrolan, dan menambahkan/menghapus peserta lain.

Sebelum memanggil metode , pastikan Anda telah memperoleh token akses dan identitas baru untuk pengguna tersebut addParticipants . Pengguna akan memerlukan token akses tersebut untuk menginisialisasi klien obrolan mereka.

addParticipantsRequest menjelaskan objek permintaan tempat participants peserta akan ditambahkan ke utas obrolan;

  • id, diperlukan, adalah pengidentifikasi komunikasi untuk ditambahkan ke utas obrolan.
  • displayName, opsional, adalah nama tampilan untuk peserta utas.
  • shareHistoryTime, opsional, adalah waktu saat riwayat obrolan dibagikan dengan peserta. Untuk membagikan riwayat sejak awal utas obrolan, atur properti ini ke tanggal yang sama dengan, atau kurang dari waktu pembuatan utas. Untuk tidak membagikan riwayat sebelum saat peserta ditambahkan, atur riwayat ke tanggal saat ini. Untuk berbagi riwayat sebagian, atur ke tanggal pilihan Anda.

const addParticipantsRequest =
{
  participants: [
    {
      id: { communicationUserId: '<NEW_PARTICIPANT_USER_ID>' },
      displayName: 'Jane'
    }
  ]
};

await chatThreadClient.addParticipants(addParticipantsRequest);

Ganti NEW_PARTICIPANT_USER_ID dengan ID pengguna baru Tambahkan kode ini sebagai ganti komentar <ADD NEW PARTICIPANT TO THREAD> di client.js

Mencantumkan pengguna di utas obrolan

const participants = chatThreadClient.listParticipants();
for await (const participant of participants) {
   // your code here
}

Tambahkan kode ini sebagai ganti komentar <LIST PARTICIPANTS IN A THREAD> di client.js, refresh tab browser Anda dan periksa konsol, Anda akan melihat informasi tentang pengguna di utas.

Menghapus pengguna dari utas obrolan

Mirip dengan menambahkan peserta, Anda dapat menghapus peserta dari utas obrolan. Untuk menghapus, Anda harus melacak ID peserta yang telah Anda tambahkan.

Gunakan metode removeParticipant yang mana participant adalah pengguna komunikasi yang akan dihapus dari utas.


await chatThreadClient.removeParticipant({ communicationUserId: <PARTICIPANT_ID> });
await listParticipants();

Ganti PARTICIPANT_ID dengan ID Pengguna yang digunakan pada langkah sebelumnya (<NEW_PARTICIPANT_USER_ID>). Tambahkan kode ini sebagai ganti komentar <REMOVE PARTICIPANT FROM THREAD> di client.js.

Berlangganan status koneksi pemberitahuan real time

Berlangganan peristiwa realTimeNotificationConnected dan realTimeNotificationDisconnected memungkinkan Anda mengetahui kapan koneksi ke server panggilan aktif.

// subscribe to realTimeNotificationConnected event
chatClient.on('realTimeNotificationConnected', () => {
  console.log("Real time notification is now connected!");
  // your code here
});
// subscribe to realTimeNotificationDisconnected event
chatClient.on('realTimeNotificationDisconnected', () => {
  console.log("Real time notification is now disconnected!");
  // your code here
});

Kode Sampel

Menemukan kode final untuk mulai cepat ini di GitHub.

Prasyarat

Sebelum memulai, pastikan untuk:

Persiapan

Membuat aplikasi Python baru

Buka terminal atau jendela perintah, buat direktori baru untuk aplikasi Anda, dan masuk ke sana.

mkdir chat-quickstart && cd chat-quickstart

Gunakan editor teks untuk membuat file bernama start-chat.py di direktori akar proyek. Tambahkan struktur program, termasuk penanganan pengecualian dasar. Di bagian berikutnya, Anda akan menambahkan semua kode sumber untuk mulai cepat ini ke dalam file ini.

import os
# Add required SDK components from quickstart here

try:
    print('Azure Communication Services - Chat Quickstart')
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

Memasang SDK

Gunakan perintah berikut untuk memasang SDK:


pip install azure-communication-chat

Model objek

Kelas dan antarmuka berikut menangani beberapa fitur utama SDK Obrolan Azure Communication Services untuk Python.

Nama Deskripsi
ChatClient Kelas ini diperlukan karena berfungsi sebagai obrolan. Anda membuat instans dari informasi langganan Anda, dan menggunakannya untuk membuat, mendapatkan, dan menghapus utas.
ChatThreadClient Kelas ini dibuat untuk fungsi Utas Obrolan. Anda mendapatkan instans melalui ChatClient, dan menggunakannya untuk mengirim, menerima, memperbarui, dan menghapus pesan. Anda juga dapat menggunakannya untuk menambahkan, menghapus, dan mendapatkan pengguna, serta mengirim pemberitahuan pengetikan dan tanda terima baca.

Membuat klien obrolan

Untuk membuat klien obrolan, gunakan titik akhir Azure Communication Services dan token akses yang Anda buat sebagai bagian dari langkah prasyarat.

pip install azure-communication-identity

from azure.communication.chat import ChatClient, CommunicationTokenCredential

endpoint = "<replace with your resource endpoint>"
chat_client = ChatClient(endpoint, CommunicationTokenCredential("<Access Token>"))

Mulai cepat ini tidak mencakup tingkat layanan untuk mengelola token untuk aplikasi obrolan Anda, tetapi hal ini direkomendasikan. Untuk informasi selengkapnya, lihat bagian "arsitektur Obrolan" pada konsep Obrolan.

Memulai utas obrolan

Gunakan metode create_chat_thread untuk membuat utas obrolan.

  • Gunakan topic untuk memberi topik pada utas. Anda dapat memperbarui topik setelah utas obrolan dibuat dengan menggunakan fungsi update_thread.
  • Gunakan thread_participants untuk mencantumkan ChatParticipant agar ditambahkan ke utas obrolan. ChatParticipant mengambil jenis CommunicationUserIdentifier sebagai user.

CreateChatThreadResult adalah hasil yang dikembalikan dari pembuatan utas. Anda dapat menggunakannya untuk mengambil id pada utas obrolan yang telah dibuat. id ini kemudian dapat digunakan untuk mengambil objek ChatThreadClient dengan menggunakan metode get_chat_thread_client. Anda dapat menggunakan ChatThreadClient untuk melakukan operasi obrolan lain pada utas obrolan ini.

topic="test topic"

create_chat_thread_result = chat_client.create_chat_thread(topic)
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

Mendapatkan klien utas obrolan

Metode get_chat_thread_client ini mengembalikan klien utas untuk utas yang sudah ada. Anda dapat menggunakannya untuk melakukan operasi di utas yang dibuat. Misalnya, Anda dapat menambahkan peserta dan mengirim pesan. thread_id adalah ID unik dari utas obrolan yang ada.

Anda dapat menggunakan ChatThreadClient untuk melakukan operasi obrolan lain pada utas obrolan ini.

thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(thread_id)

Cantumkan semua utas obrolan

Metode list_chat_threads mengembalikan iterator jenis ChatThreadItem.

  • Gunakan start_time untuk menentukan titik paling awal waktu untuk mendapatkan utas obrolan.
  • Gunakan results_per_page untuk menentukan jumlah maksimum utas obrolan yang dikembalikan per halaman.

Iterator dari [ChatThreadItem] adalah respons yang dikembalikan dari pencantuman utas.

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=2)

chat_threads = chat_client.list_chat_threads(results_per_page=5, start_time=start_time)
for chat_thread_item_page in chat_threads.by_page():
    for chat_thread_item in chat_thread_item_page:
        print(chat_thread_item)
        print('Chat Thread Id: ', chat_thread_item.id)

Mengirim pesan ke utas obrolan

Gunakan metode send_message untuk mengirim pesan ke utas obrolan yang baru saja Anda buat, yang diidentifikasi dengan thread_id.

  • Gunakan content untuk menyediakan konten pesan obrolan.
  • Gunakan chat_message_type untuk menentukan jenis konten pesan. Nilai yang memungkinan adalah text dan html. Jika Anda tidak menentukan nilai, defaultnya adalah text.
  • Gunakan sender_display_name untuk menentukan nama tampilan pengirim.
  • Gunakan metadata secara opsional untuk menyertakan data tambahan yang ingin Anda kirim bersama pesan. Bidang ini menyediakan mekanisme bagi pengembang untuk memperluas fungsionalitas pesan obrolan dan menambahkan informasi kustom untuk kasus penggunaan Anda. Misalnya, saat berbagi tautan file di pesan, Anda mungkin ingin menambahkan 'hasAttachment:true' dalam metadata sehingga aplikasi penerima dapat mengurainya dan menampilkannya.

SendChatMessageResult adalah respons yang dikembalikan dari pengiriman pesan. Ini berisi ID, yang merupakan ID unik pesan.

from azure.communication.chat import ChatMessageType

topic = "test topic"
create_chat_thread_result = chat_client.create_chat_thread(topic)
thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)


content='Please take a look at the attachment'
sender_display_name='sender name'
metadata={
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
}

# specify chat message type with pre-built enumerations
send_message_result_w_enum = chat_thread_client.send_message(content=content, sender_display_name=sender_display_name, chat_message_type=ChatMessageType.TEXT, metadata=metadata)
print("Message sent: id: ", send_message_result_w_enum.id)

Menerima pesan obrolan dari utas obrolan

Anda dapat mengambil pesan obrolan dengan melakukan polling pada metode list_messages pada interval tertentu.

  • Gunakan results_per_page untuk menentukan jumlah maksimum pesan yang akan dikembalikan per halaman.
  • Gunakan start_time untuk menentukan titik paling awal waktu untuk mendapatkan pesan.

Iterator dari [ChatMessage] adalah respons yang dikembalikan dari pencantuman pesan.

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=1)

chat_messages = chat_thread_client.list_messages(results_per_page=1, start_time=start_time)
for chat_message_page in chat_messages.by_page():
    for chat_message in chat_message_page:
        print("ChatMessage: Id=", chat_message.id, "; Content=", chat_message.content.message)

list_messages mengembalikan versi terbaru pesan, termasuk setiap pengeditan atau penghapusan yang terjadi pada pesan dengan menggunakan update_message dan delete_message. Untuk pesan yang dihapus, ChatMessage.deleted_on mengembalikan nilai datetime yang menunjukkan waktu kapan pesan ini dihapus. Untuk pesan yang diedit, ChatMessage.edited_on mengembalikan nilai datetime yang menunjukkan waktu kapan pesan diedit. Anda dapat mengakses waktu asli pembuatan pesan dengan menggunakan ChatMessage.created_on, yang dapat digunakan untuk memesan pesan.

list_messages mengembalikan jenis pesan yang berbeda, yang dapat diidentifikasi dengan ChatMessage.type.

Untuk informasi selengkapnya, lihat Jenis pesan.

Mengirim tanda terima baca

Anda menggunakan metode send_read_receipt untuk memposting peristiwa tanda terima baca ke utas, dengan atas nama pengguna.

  • Gunakan message_id untuk menentukan ID pesan terbaru yang dibaca oleh pengguna saat ini.
content='hello world'

send_message_result = chat_thread_client.send_message(content)
chat_thread_client.send_read_receipt(message_id=send_message_result.id)

Menambahkan pengguna sebagai peserta ke utas obrolan

Ketika membuat utas obrolan, Anda kemudian dapat menambahkan dan menghapus pengguna darinya. Dengan menambahkan pengguna, Anda memberi mereka akses untuk dapat mengirim pesan ke utas obrolan, dan menambahkan atau menghapus peserta lain. Sebelum memanggil metode add_participants, pastikan Anda telah memperoleh token akses dan identitas baru untuk pengguna tersebut. Pengguna memerlukan token akses tersebut untuk menginisialisasi klien obrolan.

Anda dapat menambahkan satu atau beberapa pengguna ke utas obrolan dengan menggunakan metode add_participants, dengan ketentuan token akses dan identitas baru tersedia untuk semua pengguna.

list(tuple(ChatParticipant, CommunicationError)) dikembalikan. Ketika peserta berhasil ditambahkan, daftar kosong diharapkan. Jika Anda mengalami kesalahan saat menambahkan peserta, daftar diisi dengan peserta yang gagal, bersama dengan kesalahan yang dialami.

from azure.communication.identity import CommunicationIdentityClient
from azure.communication.chat import ChatParticipant
from datetime import datetime

# create 2 users
identity_client = CommunicationIdentityClient.from_connection_string('<connection_string>')
new_users = [identity_client.create_user() for i in range(2)]

# # conversely, you can also add an existing user to a chat thread; provided the user_id is known
# from azure.communication.identity import CommunicationUserIdentifier
#
# user_id = 'some user id'
# user_display_name = "Wilma Flinstone"
# new_user = CommunicationUserIdentifier(user_id)
# participant = ChatParticipant(
#     identifier=new_user,
#     display_name=user_display_name,
#     share_history_time=datetime.utcnow())

participants = []
for _user in new_users:
  chat_thread_participant = ChatParticipant(
    identifier=_user,
    display_name='Fred Flinstone',
    share_history_time=datetime.utcnow()
  ) 
  participants.append(chat_thread_participant) 

response = chat_thread_client.add_participants(participants)

def decide_to_retry(error, **kwargs):
    """
    Insert some custom logic to decide if retry is applicable based on error
    """
    return True

# verify if all users has been successfully added or not
# in case of partial failures, you can retry to add all the failed participants 
retry = [p for p, e in response if decide_to_retry(e)]
if retry:
    chat_thread_client.add_participants(retry)

Mencantumkan peserta utas dalam utas obrolan

Serupa dengan menambahkan peserta, Anda juga dapat mencantumkan peserta dari utas.

Gunakan list_participants untuk mengambil peserta utas. Kedua perintah berikut bersifat opsional:

  • Gunakan results_per_page untuk menentukan jumlah maksimum peserta yang akan dikembalikan per halaman.
  • Gunakan skip untuk melompati peserta hingga posisi tertentu dalam respons.

Iterator dari [ChatParticipant] adalah respons yang dikembalikan dari pencantuman peserta.

chat_thread_participants = chat_thread_client.list_participants()
for chat_thread_participant_page in chat_thread_participants.by_page():
    for chat_thread_participant in chat_thread_participant_page:
        print("ChatParticipant: ", chat_thread_participant)

Jalankan kode

Menjalankan aplikasi dari direktori aplikasi Anda dengan perintah python.

python start-chat.py

Kode Sampel

Menemukan kode final untuk mulai cepat ini di GitHub.

Prasyarat

Persiapan

Membuat aplikasi Java baru

Buka terminal atau jendela perintah Anda dan arahkan ke direktori tempat Anda ingin membuat aplikasi Java. Jalankan perintah di bawah ini untuk membuat proyek Java dari templat maven-archetype-quickstart.

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Anda akan melihat bahwa tujuan 'buat' membuat direktori dengan nama yang sama dengan artifactId. Di bawah direktori ini, src/main/java directory berisi kode sumber proyek, direktori src/test/java berisi sumber pengujian, dan file pom.xml adalah Project Object Model proyek, atau POM.

Perbarui file POM aplikasi Anda untuk menggunakan Java 8 atau versi yang lebih baru:

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

Menambahkan referensi paket untuk SDK Obrolan

Dalam file POM Anda, referensikan paket azure-communication-chat dengan Chat API:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-chat for the latest version --></version>
</dependency>

Untuk autentikasi, klien Anda perlu mereferensikan paket azure-communication-common:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-common for the latest version --></version>
</dependency>

Model objek

Kelas dan antarmuka berikut menangani beberapa fitur utama SDK Obrolan Azure Communication Services untuk Java.

Nama Deskripsi
ChatClient Kelas ini diperlukan untuk fungsionalitas Obrolan. Anda membuat contoh dari informasi langganan Anda, dan menggunakannya untuk membuat, mendapatkan, dan menghapus utas.
ChatAsyncClient Kelas ini diperlukan untuk fungsionalitas Obrolan asinkron. Anda membuat contoh dari informasi langganan Anda, dan menggunakannya untuk membuat, mendapatkan, dan menghapus utas.
ChatThreadClient Kelas ini diperlukan untuk fungsionalitas Utas Obrolan. Anda mendapatkan instans melalui ChatClient dan menggunakannya untuk mengirim/menerima/memperbarui/menghapus pesan, menambah/menghapus/mendapatkan pengguna, mengirim pemberitahuan pengetikan dan tanda terima baca.
ChatThreadAsyncClient Kelas ini diperlukan untuk fungsionalitas Utas Obrolan asinkron. Anda mendapatkan instans melalui ChatAsyncClient dan menggunakannya untuk mengirim/menerima/memperbarui/menghapus pesan, menambah/menghapus/mendapatkan pengguna, mengirim pemberitahuan pengetikan dan tanda terima baca.

Membuat klien obrolan

Untuk membuat klien obrolan, Anda akan menggunakan titik akhir Communications Service dan token akses yang dibuat sebagai bagian dari langkah-langkah prasyarat. Token akses pengguna memungkinkan Anda membangun aplikasi klien yang langsung mengautentikasi ke Azure Communication Services. Setelah membuat token ini di server Anda, teruskan kembali ke perangkat klien. Anda perlu menggunakan kelas CommunicationTokenCredential dari SDK Umum untuk meneruskan token ke klien obrolan Anda.

Pelajari selengkapnya tentang Arsitektur Obrolan

Saat menambahkan laporan impor, pastikan untuk hanya menambahkan impor dari namespace com.azure.communication.chat dan com.azure.communication.chat.models, dan bukan dari namespace com.azure.communication.chat.implementation. Dalam file App.java yang dibuat melalui Maven, Anda dapat menggunakan kode berikut untuk memulai dengan:

package com.communication.quickstart;

import com.azure.communication.chat.*;
import com.azure.communication.chat.models.*;
import com.azure.communication.common.*;
import com.azure.core.http.rest.PagedIterable;

import java.io.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Chat Quickstart");

        // Your unique Azure Communication service endpoint
        String endpoint = "<replace with your resource endpoint>";

        // User access token fetched from your trusted service
        String userAccessToken = "<USER_ACCESS_TOKEN>";

        // Create a CommunicationTokenCredential with the given access token, which is only valid until the token is valid
        CommunicationTokenCredential userCredential = new CommunicationTokenCredential(userAccessToken);

        // Initialize the chat client
        final ChatClientBuilder builder = new ChatClientBuilder();
        builder.endpoint(endpoint)
            .credential(userCredential);
        ChatClient chatClient = builder.buildClient();
    }
}

Memulai utas obrolan

Gunakan metode createChatThread untuk membuat utas obrolan. createChatThreadOptions digunakan untuk mendeskripsikan permintaan utas.

  • Gunakan parameter topic konstruktor untuk memberikan topik pada obrolan ini; Topik dapat diperbarui setelah utas obrolan dibuat menggunakan fungsi UpdateThread.
  • Gunakan participants untuk mencantumkan peserta utas untuk ditambahkan ke utas. ChatParticipant membawa pengguna yang Anda buat di mulai cepat Token Akses Pengguna.

CreateChatThreadResult adalah respons yang dikembalikan dari pembuatan utas obrolan. Ini berisi metode getChatThread() yang mengembalikan objek ChatThread yang dapat digunakan untuk mendapatkan klien utas dari tempat Anda bisa mendapatkan ChatThreadClient untuk melakukan operasi pada utas yang dibuat: tambahkan peserta, kirim pesan, dll. Objek ChatThread juga berisi metode getId() yang mengambil ID unik utas.

CommunicationUserIdentifier identity1 = new CommunicationUserIdentifier("<USER_1_ID>");
CommunicationUserIdentifier identity2 = new CommunicationUserIdentifier("<USER_2_ID>");

ChatParticipant firstThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity2)
    .setDisplayName("Participant Display Name 2");

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .addParticipant(firstThreadParticipant)
    .addParticipant(secondThreadParticipant);

CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);
String chatThreadId = result.getChatThread().getId();

Daftar utas obrolan

Gunakan metode listChatThreads untuk mengambil daftar utas obrolan yang ada.

PagedIterable<ChatThreadItem> chatThreads = chatClient.listChatThreads();

chatThreads.forEach(chatThread -> {
    System.out.printf("ChatThread id is %s.\n", chatThread.getId());
});

Mendapatkan klien utas obrolan

Metode getChatThreadClient ini mengembalikan klien utas untuk utas yang sudah ada. Ini dapat digunakan untuk melakukan operasi pada utas yang dibuat: menambahkan peserta, mengirim pesan, dll. chatThreadId adalah ID unik dari utas obrolan yang ada.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Mengirim pesan ke utas obrolan

Gunakan metode sendMessage untuk mengirim pesan ke utas yang baru saja Anda buat, yang diidentifikasi oleh chatThreadId. sendChatMessageOptions digunakan untuk mendeskripsikan permintaan pesan obrolan.

  • Gunakan content untuk menyediakan konten pesan obrolan.
  • Gunakan type untuk menentukan jenis konten pesan obrolan, TEXT atau HTML.
  • Gunakan senderDisplayName untuk menentukan nama tampilan pengirim.
  • Gunakan metadata secara opsional untuk menyertakan data tambahan yang ingin Anda kirim bersama pesan. Bidang ini menyediakan mekanisme bagi pengembang untuk memperluas fungsionalitas pesan obrolan dan menambahkan informasi kustom untuk kasus penggunaan Anda. Misalnya, saat berbagi tautan file di pesan, Anda mungkin ingin menambahkan 'hasAttachment:true' dalam metadata sehingga aplikasi penerima dapat mengurainya dan menampilkannya.

Respons sendChatMessageResult berisi id, yang merupakan ID unik pesan.

Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Please take a look at the attachment")
    .setType(ChatMessageType.TEXT)
    .setSenderDisplayName("Sender Display Name")
    .setMetadata(metadata);

SendChatMessageResult sendChatMessageResult = chatThreadClient.sendMessage(sendChatMessageOptions);
String chatMessageId = sendChatMessageResult.getId();

Menerima pesan obrolan dari utas obrolan

Anda dapat mengambil pesan obrolan dengan mengumpulkan metode listMessages pada klien utas obrolan pada interval tertentu.

chatThreadClient.listMessages().forEach(message -> {
    System.out.printf("Message id is %s.\n", message.getId());
});

listMessages mengembalikan versi terbaru pesan, termasuk pengeditan atau penghapusan yang terjadi pada pesan menggunakan .editMessage() dan .deleteMessage(). Untuk pesan yang dihapus, chatMessage.getDeletedOn() mengembalikan nilai tanggalwaktu yang menunjukkan kapan pesan tersebut dihapus. Untuk pesan yang diedit, chatMessage.getEditedOn() mengembalikan tanggalwaktu yang menunjukkan kapan pesan diedit. Waktu asli pembuatan pesan dapat diakses menggunakan chatMessage.getCreatedOn(), dan dapat digunakan untuk memesan pesan.

Baca selengkapnya tentang jenis pesan di sini: Jenis Pesan.

Mengirim tanda terima baca

Gunakan metode sendReadReceipt untuk memposting peristiwa tanda terima baca ke utas obrolan, atas nama pengguna. chatMessageId adalah ID unik dari pesan obrolan yang dibaca.

String chatMessageId = message.getId();
chatThreadClient.sendReadReceipt(chatMessageId);

Daftar peserta obrolan

Gunakan listParticipants untuk mengambil kumpulan halaman yang berisi peserta utas obrolan yang diidentifikasi oleh chatThreadId.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.forEach(chatParticipant -> {
    System.out.printf("Participant id is %s.\n", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId());
});

Menambahkan pengguna sebagai peserta ke utas obrolan

Setelah utas obrolan dibuat, Anda kemudian dapat menambahkan dan menghapus pengguna darinya. Dengan menambahkan pengguna, Anda memberi mereka akses untuk mengirim pesan ke utas obrolan, dan menambahkan/menghapus peserta lain. Anda harus memulai dengan mendapatkan token akses dan identitas baru untuk pengguna tersebut. Sebelum memanggil metode addParticipants, pastikan Anda telah memperoleh token akses dan identitas baru untuk pengguna tersebut. Pengguna akan membutuhkan token akses tersebut untuk menginisialisasi klien obrolan mereka.

Gunakan metode addParticipants untuk menambahkan peserta ke utas.

  • communicationIdentifier, wajib, adalah CommunicationIdentifier yang Anda buat dengan CommunicationIdentityClient di mulai cepat Token Akses Pengguna.
  • displayName, opsional, adalah nama tampilan untuk peserta utas.
  • shareHistoryTime, opsional, adalah waktu saat riwayat obrolan dibagikan dengan peserta. Untuk membagikan riwayat sejak awal utas obrolan, atur properti ini ke tanggal yang sama dengan, atau kurang dari waktu pembuatan utas. Untuk tidak membagikan riwayat sebelum saat peserta ditambahkan, atur riwayat ke tanggal saat ini. Untuk membagikan sebagian riwayat, atur ke tanggal yang diperlukan.
List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

CommunicationUserIdentifier identity3 = new CommunicationUserIdentifier("<USER_3_ID>");
CommunicationUserIdentifier identity4 = new CommunicationUserIdentifier("<USER_4_ID>");

ChatParticipant thirdThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity3)
    .setDisplayName("Display Name 3");

ChatParticipant fourthThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity4)
    .setDisplayName("Display Name 4");

participants.add(thirdThreadParticipant);
participants.add(fourthThreadParticipant);

chatThreadClient.addParticipants(participants);

Jalankan kode

Buka direktori yang berisi file pom.xml dan kompilasikan proyek dengan perintah mvn berikut.

mvn compile

Kemudian, bangun paketnya.

mvn package

Jalankan perintah mvn berikut untuk menjalankan aplikasi.

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

Kode Sampel

Menemukan kode final untuk mulai cepat ini di GitHub.

Prasyarat

Sebelum memulai, pastikan untuk:

  • Membuat akun Azure dengan langganan aktif. Untuk mengetahui detailnya, lihat Buat akun secara gratis.

  • Install Android Studio, kami akan menggunakan Android Studio untuk membuat aplikasi Android untuk mulai cepat mengintall dependensi.

  • Membuat sumber daya Azure Communication Services. Untuk detailnya, lihat Membuat sumber daya Azure Communication Services. Anda harus merekam titik akhir sumber daya dan string koneksi untuk mulai cepat ini.

  • Buat dua Pengguna Communication Services dan terbitkan Token Akses Pengguna. Pastikan untuk mengatur cakupan ke obrolan, dan catat string token dan string user_id. Pada mulai cepat ini, kami akan membuat rangkaian dengan peserta awal dan kemudian menambahkan peserta ke dua pada rangkaian. Anda juga dapat menggunakan Azure CLI dan menjalankan perintah di bawah ini dengan string koneksi Anda untuk membuat pengguna dan token akses.

    az communication identity issue-access-token --scope chat --connection-string "yourConnectionString"

    Untuk detailnya, lihat Menggunakan Azure CLI untuk Membuat dan Mengelola Token Akses.

Persiapan

Buat aplikasi android baru

  1. Buka Android Studio dan pilih Create a new project.
  2. Pada windows selanjutnya, pilih Empty Activity sebagai templat proyek.
  3. Ketika memilih opsi, masukan ChatQuickstart sebagai nama proyek.
  4. Klik selanjurnya dan pilih petunjuk dimana Anda ingin membuat proyeknya.

Instal pustaka

Kami akan menggunakan Gradle untuk menginstall Azure Communication Services dependensi. Dari baris perintah, navigasikan kedalam direktori akar dari proyek ChatQuickstart. Buka file aplikasi build.gradle dan tambahkan dependensi dibawah ini pada ChatQuickstart target:

implementation 'com.azure.android:azure-communication-common:' + $azureCommunicationCommonVersion
implementation 'com.azure.android:azure-communication-chat:' + $azureCommunicationChatVersion
implementation 'org.slf4j:slf4j-log4j12:1.7.29'

Silakan merujuk ke https://search.maven.org/artifact/com.azure.android/azure-communication-common dan https://search.maven.org/artifact/com.azure.android/azure-communication-chat untuk angka versi terbaru.

Kecualikan file meta pada paket opsi pada build.gradle akar

android {
   ...
    packagingOptions {
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/license'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/notice'
        exclude 'META-INF/ASL2.0'
        exclude("META-INF/*.md")
        exclude("META-INF/*.txt")
        exclude("META-INF/*.kotlin_module")
    }
}

(Alternatif) Untuk menginstal pustaka melalui Maven

Untuk mengimpor pustaka pada proyek menggunakan sistem pembuatan Maven, tambahkan pada dependencies file bagian aplikasi Anda pom.xml, menentukan ID artefaknya dan versi yang ingin Anda gunakan:

<dependency>
  <groupId>com.azure.android</groupId>
  <artifactId>azure-communication-chat</artifactId>
  <version><!-- Please refer to https://search.maven.org/artifact/com.azure.android/azure-communication-chat for the latest version --></version>
</dependency>

Siapkan tempat penampung

Buka dan edit file MainActivity.java. Pada mulai cepat ini, kami akan menambahkan kode padaMainActivity, dan melihat outpul di konsol. Mulai cepat ini tidak membaha pembuatan IU. Pada bagian atas, impor Communication common, Communication chat, dan sistem pustaka lain:

import com.azure.android.communication.chat.*;
import com.azure.android.communication.chat.models.*;
import com.azure.android.communication.common.*;

import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;

import com.jakewharton.threetenabp.AndroidThreeTen;

import java.util.ArrayList;
import java.util.List;

Salin kode berikut pada kelas MainActivity dalam file MainActivity.java:

    private String endpoint = "<replace with your resource endpoint>'";
    private String firstUserId = "<first_user_id>";
    private String secondUserId = "<second_user_id>";
    private String firstUserAccessToken = "<first_user_access_token>";
    private String threadId = "<thread_id>";
    private String chatMessageId = "<chat_message_id>";
    private final String sdkVersion = "<chat_sdk_version>";
    private static final String APPLICATION_ID = "Chat Quickstart App";
    private static final String SDK_NAME = "azure-communication-com.azure.android.communication.chat";
    private static final String TAG = "Chat Quickstart App";
    private ChatAsyncClient chatAsyncClient;

    private void log(String msg) {
        Log.i(TAG, msg);
        Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
    }
    
   @Override
    protected void onStart() {
        super.onStart();
        try {
            AndroidThreeTen.init(this);

            // <CREATE A CHAT CLIENT>

            // <CREATE A CHAT THREAD>

            // <CREATE A CHAT THREAD CLIENT>

            // <SEND A MESSAGE>
            
            // <RECEIVE CHAT MESSAGES>

            // <ADD A USER>

            // <LIST USERS>

            // <REMOVE A USER>
            
            // <<SEND A TYPING NOTIFICATION>>
            
            // <<SEND A READ RECEIPT>>
               
            // <<LIST READ RECEIPTS>>
        } catch (Exception e){
            System.out.println("Quickstart failed: " + e.getMessage());
        }
    }
  1. Ganti <resource> dengan sumber daya Azure Communication Services Anda.
  2. Ganti <first_user_id> dan <second_user_id> dengan ID pengguna Azure Communication Services yang valid yang dibuat sebagai bagian dari langkah-langkah prasyarat.
  3. Ganti <first_user_access_token> dengan token akses Azure Communication Services untuk <first_user_id> yang dibuat sebagai bagian dari langkah-langkah prasyarat.
  4. Ganti <chat_sdk_version> dengan versi Azure Communication Chat SDK.

Pada langkah-langkah berikut, kami mengganti placeholders dengan kode sample menggunakan obrolan pustaka Azure Communication Services.

Membuat klien obrolan

Ganti komentar <CREATE A CHAT CLIENT> dengan kode berikut (letakkan pernyataan impor di atas file):

import com.azure.android.core.http.policy.UserAgentPolicy;

chatAsyncClient = new ChatClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .buildAsyncClient();

Model objek

Kelas dan tatap muka berikut menangani beberapa fitur utama SDK Obrolan Azure Communication Services untuk JavaScript.

Nama Deskripsi
ChatClient/ChatAsyncClient Kelas ini diperlukan karena berfungsi sebagai obrolan. Anda membuat instans dari informasi langganan Anda, dan menggunakannya untuk membuat, mendapatkan, menghapus utas, dan berlangganan acara obrolan.
ChatThreadClient/ChatThreadAsyncClient Kelas ini dibuat untuk fungsi Utas Obrolan. Anda mendapatkan instans melalui ChatClient dan menggunakannya untuk mengirim/menerima/memperbarui/menghapus pesan, menambah/menghapus/mendapatkan pengguna, mengirim pemberitahuan pengetikan dan tanda terima baca.

Memulai utas obrolan

Kami akan menggunakan ChatAsyncClient untuk membuat utas baru dengan pengguna awal.

Ganti komentar <CREATE A CHAT THREAD> dengan kode berikut:

// A list of ChatParticipant to start the thread with.
List<ChatParticipant> participants = new ArrayList<>();
// The display name for the thread participant.
String displayName = "initial participant";
participants.add(new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(firstUserId))
    .setDisplayName(displayName));

// The topic for the thread.
final String topic = "General";
// Optional, set a repeat request ID.
final String repeatabilityRequestID = "";
// Options to pass to the create method.
CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions()
    .setTopic(topic)
    .setParticipants(participants)
    .setIdempotencyToken(repeatabilityRequestID);

CreateChatThreadResult createChatThreadResult =
    chatAsyncClient.createChatThread(createChatThreadOptions).get();
ChatThreadProperties chatThreadProperties = createChatThreadResult.getChatThreadProperties();
threadId = chatThreadProperties.getId();

Mendapatkan seorang klien utas obrolan

Sekarang setelah kami membuat utas Obrolan, kami akan mendapatkan ChatThreadAsyncClient untuk melakukan pekerjaan di dalam utas. Ganti komentar <CREATE A CHAT THREAD CLIENT> dengan kode berikut:

ChatThreadAsyncClient chatThreadAsyncClient = new ChatThreadClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .chatThreadId(threadId)
    .buildAsyncClient();

Mengirim pesan ke utas obrolan

Kami akan mengirim pesan ke utas tersebut sekarang.

Ganti komentar <SEND A MESSAGE> dengan kode berikut:

// The chat message content, required.
final String content = "Please take a look at the attachment";

// The display name of the sender, if null (i.e. not specified), an empty name will be set.
final String senderDisplayName = "An important person";

// Use metadata optionally to include any additional data you want to send along with the message.
// This field provides a mechanism for developers to extend chat message functionality and add
// custom information for your use case. For example, when sharing a file link in the message, you
// might want to add 'hasAttachment:true' in metadata so that recipient's application can parse
// that and display accordingly.
final Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions chatMessageOptions = new SendChatMessageOptions()
    .setType(ChatMessageType.TEXT)
    .setContent(content)
    .setSenderDisplayName(senderDisplayName)
    .setMetadata(metadata);

// A string is the response returned from sending a message, it is an id, which is the unique ID
// of the message.
chatMessageId = chatThreadAsyncClient.sendMessage(chatMessageOptions).get().getId();

Menerima pesan obrolan dari utas obrolan

Pemberitahuan real-time

Dengan real-time signaling, Anda dapat berlangganan pesan masuk baru dan memperbarui pesan saat ini di memori. Azure Communication Services mendukung daftar acar yang dapat Anda ikuti untuk .

Ganti komentar <RECEIVE CHAT MESSAGES> dengan kode berikut (letakkan pernyataan impor di atas file):


// Start real time notification
chatAsyncClient.startRealtimeNotifications(firstUserAccessToken, getApplicationContext());

// Register a listener for chatMessageReceived event
chatAsyncClient.addEventHandler(ChatEventType.CHAT_MESSAGE_RECEIVED, (ChatEvent payload) -> {
    ChatMessageReceivedEvent chatMessageReceivedEvent = (ChatMessageReceivedEvent) payload;
    // You code to handle chatMessageReceived event
    
});

Penting

Masalah yang diketahui: Saat menggunakan Android Chat dan Calling SDK secara bersamaan dalam aplikasi yang sama, fitur notifikasi waktu nyata Chat SDK tidak berfungsi. Anda mungkin mendapatkan masalah penyelesaian dependensi. Saat kami sedang mengerjakan solusi, Anda dapat menonaktifkan fitur notifikasi real-time dengan menambahkan informasi dependesi berikut pada file aplikasi build.gradle dan sebagai gantinya melakukan polling pada GetMessages API untuk menampilkan pesan masuk kepada pengguna.

implementation ("com.azure.android:azure-communication-chat:1.0.0") {
    exclude group: 'com.microsoft', module: 'trouter-client-android'
}
implementation 'com.azure.android:azure-communication-calling:1.0.0'

Perhatikan pembaruan di atas, jika aplikasi mencoba menyentuh salah satu notifikasi API seperti chatAsyncClient.startRealtimeNotifications() or chatAsyncClient.addEventHandler(), akan ada kesalahan runtime.

Pemberitahuan push

Catatan

Saat ini pemberitahuan push obrolan hanya didukung untuk Android SDK di versi 1.1.0-beta.4.

Pemberitahuan push memungkinkan klien diberi tahu untuk pesan masuk dan operasi lain yang terjadi di utas obrolan dalam situasi di mana aplikasi seluler tidak berjalan di latar depan. Azure Communication Services mendukung daftar peristiwa yang dapat Anda ikuti.

  1. Siapkan Firebase Cloud Messaging dengan proyek ChatQuickstart. Selesaikan langkah- langkah Create a Firebase project, Register your app with Firebase, Add a Firebase configuration file, Add Firebase SDKs to your app, dan Edit your app manifest dalam Dokumentasi Firebase.

  2. Buat Notification Hub dalam langganan yang sama dengan sumber daya Communication Services Anda, konfigurasikan pengaturan Firebase Cloud Messaging untuk hub, dan tautkan Notification Hub ke sumber daya Communication Services Anda. Lihat Provisi Notification Hub.

  3. Buat file MyFirebaseMessagingService.java baru di jalur file MainActivity.javayang sama. Salin kode berikut ke dalam file MyFirebaseMessagingService.java. Anda perlu mengganti <your_package_name> dengan nama paket yang digunakan dalam MainActivity.java. Anda dapat menggunakan nilai Anda sendiri untuk <your_intent_name>. Nilai ini akan digunakan pada langkah 6 di bawah ini.

       package <your_package_name>;

   import android.content.Intent;
   import android.util.Log;

   import androidx.localbroadcastmanager.content.LocalBroadcastManager;

   import com.azure.android.communication.chat.models.ChatPushNotification;
   import com.google.firebase.messaging.FirebaseMessagingService;
   import com.google.firebase.messaging.RemoteMessage;

   import java.util.concurrent.Semaphore;

   public class MyFirebaseMessagingService extends FirebaseMessagingService {
       private static final String TAG = "MyFirebaseMsgService";
       public static Semaphore initCompleted = new Semaphore(1);

       @Override
       public void onMessageReceived(RemoteMessage remoteMessage) {
           try {
               Log.d(TAG, "Incoming push notification.");

               initCompleted.acquire();

               if (remoteMessage.getData().size() > 0) {
                   ChatPushNotification chatPushNotification =
                       new ChatPushNotification().setPayload(remoteMessage.getData());
                   sendPushNotificationToActivity(chatPushNotification);
               }

               initCompleted.release();
           } catch (InterruptedException e) {
               Log.e(TAG, "Error receiving push notification.");
           }
       }

       private void sendPushNotificationToActivity(ChatPushNotification chatPushNotification) {
           Log.d(TAG, "Passing push notification to Activity: " + chatPushNotification.getPayload());
           Intent intent = new Intent("<your_intent_name>");
           intent.putExtra("PushNotificationPayload", chatPushNotification);
           LocalBroadcastManager.getInstance(this).sendBroadcast(intent);
       }
   }

  4. Di bagian atas file MainActivity.java, tambahkan impor berikut:

       import android.content.BroadcastReceiver;
   import android.content.Context;
   import android.content.Intent;
   import android.content.IntentFilter;

   import androidx.localbroadcastmanager.content.LocalBroadcastManager;
   import com.azure.android.communication.chat.models.ChatPushNotification;
   import com.google.android.gms.tasks.OnCompleteListener;
   import com.google.android.gms.tasks.Task;
   import com.google.firebase.messaging.FirebaseMessaging;

  5. Tambahkan kode berikut ke dalam kelas MainActivity:

       private BroadcastReceiver firebaseMessagingReceiver = new BroadcastReceiver() {
       @Override
       public void onReceive(Context context, Intent intent) {
           ChatPushNotification pushNotification =
               (ChatPushNotification) intent.getParcelableExtra("PushNotificationPayload");

           Log.d(TAG, "Push Notification received in MainActivity: " + pushNotification.getPayload());

           boolean isHandled = chatAsyncClient.handlePushNotification(pushNotification);
           if (!isHandled) {
               Log.d(TAG, "No listener registered for incoming push notification!");
           }
       }
   };


   private void startFcmPushNotification() {
       FirebaseMessaging.getInstance().getToken()
           .addOnCompleteListener(new OnCompleteListener<String>() {
               @Override
               public void onComplete(@NonNull Task<String> task) {
                   if (!task.isSuccessful()) {
                       Log.w(TAG, "Fetching FCM registration token failed", task.getException());
                       return;
                   }

                   // Get new FCM registration token
                   String token = task.getResult();

                   // Log and toast
                   Log.d(TAG, "Fcm push token generated:" + token);
                   Toast.makeText(MainActivity.this, token, Toast.LENGTH_SHORT).show();

                   chatAsyncClient.startPushNotifications(token, new Consumer<Throwable>() {
                       @Override
                       public void accept(Throwable throwable) {
                           Log.w(TAG, "Registration failed for push notifications!", throwable);
                       }
                   });
               }
           });
   }

  6. Perbarui fungsi onCreate di kelas MainActivity.

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

       LocalBroadcastManager
           .getInstance(this)
           .registerReceiver(
               firebaseMessagingReceiver,
               new IntentFilter("<your_intent_name>"));
   }

  7. Masukkan kode berikut di bawah komentar <RECEIVE CHAT MESSAGES>:

   startFcmPushNotification();

   chatAsyncClient.addPushNotificationHandler(CHAT_MESSAGE_RECEIVED, (ChatEvent payload) -> {
       Log.i(TAG, "Push Notification CHAT_MESSAGE_RECEIVED.");
       ChatMessageReceivedEvent event = (ChatMessageReceivedEvent) payload;
       // You code to handle ChatMessageReceived event
   });

Tambahkan pengguna sebagai peserta ke utas obrolan

Ganti komentar <ADD A USER> dengan kode berikut:

// The display name for the thread participant.
String secondUserDisplayName = "a new participant";
ChatParticipant participant = new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(secondUserId))
    .setDisplayName(secondUserDisplayName);
        
chatThreadAsyncClient.addParticipant(participant);

Mencantumkan Daftar pengguna di utas

Ganti <LIST USERS> komentar dengan kode berikut (letakan pernyataan impor pada bagian atas file):

import com.azure.android.core.rest.util.paging.PagedAsyncStream;
import com.azure.android.core.util.RequestContext;

// The maximum number of participants to be returned per page, optional.
int maxPageSize = 10;

// Skips participants up to a specified position in response.
int skip = 0;

// Options to pass to the list method.
ListParticipantsOptions listParticipantsOptions = new ListParticipantsOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatParticipant> participantsPagedAsyncStream =
      chatThreadAsyncClient.listParticipants(listParticipantsOptions, RequestContext.NONE);

participantsPagedAsyncStream.forEach(chatParticipant -> {
    // You code to handle participant
});

Hapus pengguna dari utas obrolan

Kami akan menghapus pengguna ke dua dari utas sekarang.

Ganti komentar<REMOVE A USER> dengan kode berikut:

// Using the unique ID of the participant.
chatThreadAsyncClient.removeParticipant(new CommunicationUserIdentifier(secondUserId)).get();

Kirim pemberitahuan pengetikan

Ganti komentar <SEND A TYPING NOTIFICATION> dengan kode berikut:

chatThreadAsyncClient.sendTypingNotification().get();

Kirim tanda terima baca

Kami akan mengirimkan tanda terima baca untuk pesan yang dikirim di atas.

Ganti komentar <SEND A READ RECEIPT> dengan kode berikut:

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Daftar tanda terima yang telah dibaca

Ganti komentar <READ RECEIPTS> dengan kode berikut:

// The maximum number of participants to be returned per page, optional.
maxPageSize = 10;
// Skips participants up to a specified position in response.
skip = 0;
// Options to pass to the list method.
ListReadReceiptOptions listReadReceiptOptions = new ListReadReceiptOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatMessageReadReceipt> readReceiptsPagedAsyncStream =
      chatThreadAsyncClient.listReadReceipts(listReadReceiptOptions, RequestContext.NONE);

readReceiptsPagedAsyncStream.forEach(readReceipt -> {
    // You code to handle readReceipt
});

Jalankan kode

Di Android Studio, tekan tombol Run untuk membuat dan menjalankan proyek. Pada konsol, Anda dapat melihat output dari kode dan output logger dari ChatClient.

Kode Sampel

Menemukan kode final untuk mulai cepat ini di GitHub.

Prasyarat

Sebelum memulai, pastikan untuk:

Persiapan

Membuat aplikasi C# baru

Di jendela konsol (seperti cmd, PowerShell, atau Bash), gunakan perintah dotnet new untuk membuat aplikasi konsol baru dengan nama ChatQuickstart. Perintah ini membuat proyek C# "Halo Dunia" sederhana dengan satu file sumber: Program.cs.

dotnet new console -o ChatQuickstart

Ubah direktori Anda ke folder aplikasi yang baru dibuat dan gunakan perintah dotnet build untuk mengompilasi aplikasi Anda.

cd ChatQuickstart
dotnet build

Menginstal paket

Menginstal Azure Communication Chat SDK untuk .NET

dotnet add package Azure.Communication.Chat

Model objek

Kelas berikut menangani beberapa fitur utama Azure Communication Services Chat SDK untuk C#.

Nama Deskripsi
ChatClient Kelas ini diperlukan untuk fungsionalitas Obrolan. Anda membuat contoh dari informasi langganan Anda, dan menggunakannya untuk membuat, mendapatkan, dan menghapus utas.
ChatThreadClient Kelas ini diperlukan untuk fungsionalitas Utas Obrolan. Anda mendapatkan instans melalui ChatClient dan menggunakannya untuk mengirim/menerima/memperbarui/menghapus pesan, menambahkan/menghapus/mendapatkan peserta, mengirim pemberitahuan pengetikan, dan membaca tanda terima.

Membuat klien obrolan

Untuk membuat klien obrolan, Anda akan menggunakan titik akhir Communication Services dan token akses yang dihasilkan sebagai bagian dari langkah-langkah prasyarat. Anda perlu menggunakan kelas CommunicationIdentityClient dari SDK Identitas untuk membuat pengguna dan menerbitkan token untuk diteruskan ke klien obrolan Anda.

Pelajari selengkapnya tentang Token Akses Pengguna.

Panduan mulai cepat ini tidak mencakup pembuatan tingkat layanan untuk mengelola token untuk aplikasi obrolan Anda, meskipun direkomendasikan. Pelajari selengkapnya tentang Arsitektur Obrolan

Salin cuplikan kode berikut dan tempelkan ke file sumber: Program.cs

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Azure Communication service endpoint
            Uri endpoint = new Uri("<replace with your resource endpoint>");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Memulai utas obrolan

Gunakan metode createChatThread pada chatClient untuk membuat utas obrolan

  • Gunakan topic untuk memberikan topik pada obrolan ini; Topik dapat diperbarui setelah utas obrolan dibuat menggunakan fungsi UpdateTopic.
  • Gunakan participants properti untuk meneruskan daftar ChatParticipant objek yang akan ditambahkan ke utas obrolan. Objek ChatParticipant diinisialisasi dengan objek CommunicationIdentifier. CommunicationIdentifier bisa berupa jenis CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, atau PhoneNumberIdentifier. Misalnya, untuk mendapatkan objek CommunicationIdentifier, Anda harus meneruskan ID Akses yang Anda buat dengan mengikuti petunjuk untuk Membuat pengguna

Objek respons dari metode createChatThread berisi detail chatThread. Untuk berinteraksi dengan operasi utas obrolan seperti menambahkan peserta, mengirim pesan, menghapus pesan, dll., instans klien chatThreadClient perlu diinisiasi menggunakan metode GetChatThreadClient pada klien ChatClient.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<Access_ID>"))
{
    DisplayName = "UserDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Mendapatkan klien utas obrolan

Metode GetChatThreadClient mengembalikan klien utas untuk utas yang sudah ada. Ini dapat digunakan untuk melakukan operasi pada utas yang dibuat: menambahkan anggota, mengirim pesan, dll. threadId adalah ID unik dari utas obrolan yang sudah ada.

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Mencantumkan semua utas obrolan

Gunakan GetChatThreads untuk mengambil semua utas obrolan tempat pengguna menjadi bagiannya.

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

Mengirim pesan ke utas obrolan

Gunakan SendMessage untuk mengirim pesan ke utas.

  • Gunakan content untuk menyediakan konten untuk pesan karena itu diperlukan.
  • Gunakan type untuk jenis konten pesan seperti 'Teks' atau 'Html'. Jika tidak ditentukan, akan diatur sebagai 'Teks'.
  • Gunakan senderDisplayName untuk menentukan nama tampilan pengirim. Jika tidak ditentukan, akan diatur sebagai string kosong.
  • Gunakan metadata secara opsional untuk menyertakan data tambahan yang ingin Anda kirim bersama pesan. Bidang ini menyediakan mekanisme bagi pengembang untuk memperluas fungsionalitas pesan obrolan dan menambahkan informasi kustom untuk kasus penggunaan Anda. Misalnya, saat berbagi tautan file di pesan, Anda mungkin ingin menambahkan 'hasAttachment:true' dalam metadata sehingga aplikasi penerima dapat mengurainya dan menampilkannya.
SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Please take a look at the attachment",
    MessageType = ChatMessageType.Text
};
sendChatMessageOptions.Metadata["hasAttachment"] = "true";
sendChatMessageOptions.Metadata["attachmentUrl"] = "https://contoso.com/files/attachment.docx";

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Menerima pesan obrolan dari utas obrolan

Anda dapat mengambil pesan obrolan dengan mengumpulkan metode GetMessages pada klien utas obrolan pada interval yang ditentukan.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

GetMessages mengambil parameter DateTimeOffset opsional. Jika offset tersebut ditentukan, Anda akan menerima pesan yang diterima, diperbarui, atau dihapus setelahnya. Perhatikan bahwa pesan yang diterima sebelum waktu offset tetapi diedit atau dihapus setelahnya juga akan ditampilkan.

GetMessages menampilkan versi terbaru pesan, termasuk pengeditan atau penghapusan yang terjadi pada pesan menggunakan UpdateMessage dan DeleteMessage. Untuk pesan yang dihapus, chatMessage.DeletedOn akan menampilkan nilai tanggalwaktu yang menunjukkan kapan pesan tersebut dihapus. Untuk pesan yang diedit, chatMessage.EditedOn mengembalikan tanggalwaktu yang menunjukkan kapan pesan diedit. Waktu asli pembuatan pesan dapat diakses menggunakan chatMessage.CreatedOn dan dapat digunakan untuk mengurutkan pesan.

GetMessages menampilkan berbagai jenis pesan yang dapat diidentifikasi oleh chatMessage.Type. Jenis-jenisnya adalah:

  • Text: Pesan obrolan biasa yang dikirim oleh anggota utas.

  • Html: Pesan teks yang diformat. Perhatikan bahwa pengguna Communication Services saat ini tidak dapat mengirim pesan RichText. Jenis pesan ini didukung oleh pesan yang dikirim dari pengguna Teams ke pengguna Communication Services dalam skenario Interop Teams.

  • TopicUpdated: Pesan sistem yang menunjukkan bahwa topik telah diperbarui. (readonly)

  • ParticipantAdded: Pesan sistem yang menunjukkan bahwa satu atau beberapa peserta telah ditambahkan ke utas obrolan.(readonly)

  • ParticipantRemoved: Pesan sistem yang menunjukkan bahwa peserta telah dihapus dari utas obrolan.

Untuk detail selengkapnya, lihat Jenis Pesan.

Menambahkan pengguna sebagai peserta ke utas obrolan

Setelah utas dibuat, Anda kemudian dapat menambahkan dan menghapus pengguna darinya. Dengan menambahkan pengguna, Anda memberi mereka akses untuk dapat mengirim pesan ke utas dan menambahkan/menghapus peserta lain. Sebelum menghubungi AddParticipants, pastikan Anda telah memperoleh token akses dan identitas baru untuk pengguna tersebut. Pengguna akan membutuhkan token akses tersebut untuk menginisialisasi klien obrolan mereka.

Gunakan AddParticipants untuk menambahkan satu atau beberapa peserta ke utas obrolan. Berikut ini adalah atribut yang didukung untuk setiap peserta utas:

  • communicationUser, wajib, adalah identitas peserta utas.
  • displayName, opsional, adalah nama tampilan untuk peserta utas.
  • shareHistoryTime, opsional, adalah waktu ketika riwayat obrolan dibagikan dengan peserta.
var josh = new CommunicationUserIdentifier(id: "<Access_ID_For_Josh>");
var gloria = new CommunicationUserIdentifier(id: "<Access_ID_For_Gloria>");
var amy = new CommunicationUserIdentifier(id: "<Access_ID_For_Amy>");

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants: participants);

Mendapatkan peserta utas

Gunakan GetParticipants untuk mengambil peserta utas obrolan.

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

Mengirim tanda terima dibaca

Gunakan SendReadReceipt untuk memberi tahu peserta lain bahwa pesan telah dibaca oleh pengguna.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Jalankan kode

Menjalankan aplikasi dari direktori aplikasi Anda dengan perintah dotnet run.

dotnet run

Kode Sampel

Menemukan kode final untuk mulai cepat ini di GitHub.

Prasyarat

Sebelum memulai, pastikan untuk:

  • Membuat akun Azure dengan langganan aktif. Untuk mengetahui detailnya, lihat Buat akun secara gratis.

  • Instal Xcode dan CocoaPods. Anda dapat menggunakan Xcode untuk membuat aplikasi iOS untuk pemula, dan CocoaPods untuk menginstal dependensi.

  • Membuat sumber daya Azure Communication Services. Untuk mengetahui detailnya, lihat Mulai cepat: Buat dan kelola sumber daya Azure Communication Services. Anda harus merekam titik akhir sumber daya dan string koneksi untuk mulai cepat ini.

  • Buat dua pengguna di Azure Communication Services, dan terbitkan Token Akses Pengguna. Pastikan untuk mengatur cakupan ke obrolan, dan catat string token serta string user_id. Dalam mulai cepat ini, Anda membuat utas dengan peserta pertama, lalu tambahkan peserta kedua ke utas. Anda juga dapat menggunakan Azure CLI dan menjalankan perintah di bawah ini dengan string koneksi Anda untuk membuat pengguna dan token akses.

    az communication identity issue-access-token --scope chat --connection-string "yourConnectionString"

    Untuk detailnya, lihat Menggunakan Azure CLI untuk Membuat dan Mengelola Token Akses.

Persiapan

Buat aplikasi iOS baru

Buka Xcode dan pilih Buat proyek Xcode baru. Kemudian pilih iOS sebagai platform dan Aplikasi untuk templat.

Untuk nama proyek, masukkan ChatQuickstart. Kemudian pilih Storyboard sebagai antarmuka, Delegasi Aplikasi UIKit sebagai siklus hidup, dan Swift sebagai bahasa.

Pilih Berikutnya, dan pilih direktori tempat Anda ingin proyek dibuat.

Instal pustaka

Gunakan CocoaPods untuk menginstal dependensi Azure Communication Services yang diperlukan.

Dari baris perintah, masuk ke dalam akar direktori proyek ChatQuickstart iOS. Buat Podfile dengan perintah berikut: pod init.

Buka Podfile, dan tambahkan dependensi berikut ke ChatQuickstart target:

pod 'AzureCommunicationCommon', '~> 1.0.3'
pod 'AzureCommunicationChat', '~> 1.2.0'

Instal dependensi dengan perintah berikut: pod install. Perhatikan bahwa hal ini juga membuat ruang kerja Xcode.

Setelah menjalankan pod install, buka kembali proyek di Xcode dengan memilih .xcworkspaceyang baru saja dibuat.

Siapkan tempat penampung

Buka ruang kerja ChatQuickstart.xcworkspace di Xcode, lalu buka ViewController.swift.

Dalam mulai cepat, Anda menambahkan kode Anda ke viewController, dan melihat output di konsol Xcode. Panduan mulai cepat tidak membahas pembuatan tatap muka pengguna di iOS.

Di bagian atas viewController.swift, impor AzureCommunication dan AzureCommunicatonChat pustaka:

import AzureCommunicationCommon
import AzureCommunicationChat

Salin kode berikut ke viewDidLoad() dalam metode ViewController :

override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.

        let semaphore = DispatchSemaphore(value: 0)
        DispatchQueue.global(qos: .background).async {
            do {
                // <CREATE A CHAT CLIENT>
                
                // <CREATE A CHAT THREAD>

                // <LIST ALL CHAT THREADS>

                // <GET A CHAT THREAD CLIENT>

                // <SEND A MESSAGE>

                // <SEND A READ RECEIPT >

                // <RECEIVE MESSAGES>

                // <ADD A USER>
                
                // <LIST USERS>
            } catch {
                print("Quickstart failed: \(error.localizedDescription)")
            }
        }
    }

Untuk tujuan demonstrasi, kami akan menggunakan semaphore untuk menyinkronkan kode Anda. Dalam langkah-langkah berikut, Anda mengganti tempat penampung dengan kode sampel dengan menggunakan pustaka Obrolan Azure Communication Services.

Membuat klien obrolan

Untuk membuat klien obrolan, Anda akan menggunakan titik akhir Communication Services dan token akses yang dihasilkan sebagai bagian dari langkah-langkah prasyarat.

Pelajari selengkapnya tentang Token Akses Pengguna.

Panduan mulai cepat ini tidak mencakup pembuatan tingkat layanan untuk mengelola token untuk aplikasi obrolan Anda, meskipun direkomendasikan. Pelajari selengkapnya tentang Arsitektur Obrolan

Ganti komentar <CREATE A CHAT CLIENT> dengan cuplikan kode berikut:

let endpoint = "<ACS_RESOURCE_ENDPOINT>"
let credential =
try CommunicationTokenCredential(
    token: "<ACCESS_TOKEN>"
)
let options = AzureCommunicationChatClientOptions()

let chatClient = try ChatClient(
    endpoint: endpoint,
    credential: credential,
    withOptions: options
)

Ganti <ACS_RESOURCE_ENDPOINT> dengan titik akhir untuk sumber daya Azure Communication Services Anda. Ganti <ACCESS_TOKEN> dengan token akses Azure Communication Services Anda yang valid.

Model objek

Kelas dan antarmuka berikut menangani beberapa fitur utama SDK Obrolan Azure Communication Services untuk iOS.

Nama Deskripsi
ChatClient Kelas ini diperlukan karena berfungsi sebagai obrolan. Anda membuat contoh dengan informasi langganan Anda, dan menggunakannya untuk membuat, mendapatkan, menghapus utas, dan berlangganan peristiwa obrolan.
ChatThreadClient Kelas ini dibuat untuk fungsi Utas Obrolan. Anda mendapatkan instans melalui ChatClient, dan menggunakannya untuk mengirim, menerima, memperbarui, dan menghapus pesan. Anda juga dapat menggunakannya untuk menambahkan, menghapus, dan mendapatkan pengguna, serta mengirim pemberitahuan pengetikan dan tanda terima baca.

Memulai utas obrolan

CreateChatThreadResult adalah respons yang dikembalikan dari pembuatan utas obrolan. Ini berisi properti chatThread yang merupakan objek ChatThreadProperties. Objek ini berisi threadId yang dapat digunakan untuk mendapatkan ChatThreadClient untuk melakukan operasi di alur yang dibuat: menambahkan peserta, mengirim pesan, dll.

Ganti komentar <CREATE A CHAT THREAD> dengan cuplikan kode berikut:

let request = CreateChatThreadRequest(
    topic: "Quickstart",
    participants: [
        ChatParticipant(
            id: CommunicationUserIdentifier("<USER_ID>"),
            displayName: "Jack"
        )
    ]
)

var threadId: String?
chatClient.create(thread: request) { result, _ in
    switch result {
    case let .success(result):
        threadId = result.chatThread?.id

    case .failure:
        fatalError("Failed to create thread.")
    }
    semaphore.signal()
}
semaphore.wait()

Ganti <USER_ID> dengan token akses Azure Communication Services Anda yang valid.

Anda menggunakan semaphore di sini untuk menunggu pengatur untuk menyelesaikan sebelum melanjutkan. Dalam langkah selanjutnya, Anda akan menggunakan threadId dari respons yang dikembalikan ke pengatur penyelesaian.

Mencantumkan semua utas obrolan

Setelah membuat utas obrolan, kita dapat mencantumkan semua utas obrolan dengan memanggil listChatThreads metode pada ChatClient. Ganti komentar <LIST ALL CHAT THREADS> dengan kode berikut:

chatClient.listThreads { result, _ in
    switch result {
    case let .success(threads):
        guard let chatThreadItems = threads.pageItems else {
            print("No threads returned.")
            return
        }

        for chatThreadItem in chatThreadItems {
            print("Thread id: \(chatThreadItem.id)")
        }
    case .failure:
        print("Failed to list threads")
    }
    semaphore.signal()
}
semaphore.wait()

Mendapatkan klien utas obrolan

Metode createClient menampilkan ChatThreadClient untuk utas yang sudah ada. Ini dapat digunakan untuk melakukan operasi pada utas yang dibuat: menambahkan peserta, mengirim pesan, dll. threadId adalah ID unik dari utas obrolan yang ada.

Ganti komentar <GET A CHAT THREAD CLIENT> dengan kode berikut:

let chatThreadClient = try chatClient.createClient(forThread: threadId!)

Mengirim pesan ke utas obrolan

Gunakan metode send untuk mengirim pesan ke alur yang diidentifikasi oleh threadId.

SendChatMessageRequest digunakan untuk menjelaskan permintaan pesan:

  • Gunakan content untuk memasukkan konten pesan obrolan
  • Gunakan senderDisplayName untuk menentukan nama tampilan pengirim
  • Gunakan type untuk menentukan jenis pesan, seperti 'text' atau 'html'
  • Gunakan metadata secara opsional untuk menyertakan data tambahan yang ingin Anda kirim bersama pesan. Bidang ini menyediakan mekanisme bagi pengembang untuk memperluas fungsionalitas pesan obrolan dan menambahkan informasi kustom untuk kasus penggunaan Anda. Misalnya, saat berbagi tautan file di pesan, Anda mungkin ingin menambahkan 'hasAttachment:true' dalam metadata sehingga aplikasi penerima dapat mengurainya dan menampilkannya.

SendChatMessageResult adalah respons yang ditampilkan dari mengirim pesan, berisi ID, yang merupakan ID unik pesan.

Ganti komentar <SEND A MESSAGE> dengan cuplikan kode berikut:

let message = SendChatMessageRequest(
                        content: "Hello!",
                        senderDisplayName: "Jack",
                        type: .text,
                        metadata: [
                            "hasAttachment": "true",
                            "attachmentUrl": "https://contoso.com/files/attachment.docx"
                        ]
                    )

var messageId: String?

chatThreadClient.send(message: message) { result, _ in
    switch result {
    case let .success(result):
        print("Message sent, message id: \(result.id)")
        messageId = result.id
    case .failure:
        print("Failed to send message")
    }
    semaphore.signal()
}
semaphore.wait()

Kirim tanda terima baca

Gunakan metode sendReadReceipt untuk memposting peristiwa tanda terima baca ke utas obrolan, atas nama pengguna. messageId adalah ID unik dari pesan obrolan yang dibaca.

Ganti komentar <SEND A READ RECEIPT> dengan kode berikut:

if let id = messageId {
    chatThreadClient.sendReadReceipt(forMessage: id) { result, _ in
        switch result {
        case .success:
            print("Read receipt sent")
        case .failure:
            print("Failed to send read receipt")
        }
        semaphore.signal()
    }
    semaphore.wait()
} else {
    print("Cannot send read receipt without a message id")
}

Menerima pesan obrolan dari utas obrolan

Dengan sinyal real time, Anda dapat berlangganan untuk mendengarkan pesan masuk baru dan memperbarui pesan saat ini di memori. Azure Communication Services mendukung daftar peristiwa yang dapat Anda ikuti.

Ganti komentar <RECEIVE MESSAGES> dengan kode berikut. Setelah mengaktifkan pemberitahuan, coba kirim pesan baru untuk melihat ChatMessageReceivedEvents.

chatClient.startRealTimeNotifications { result in
    switch result {
    case .success:
        print("Real-time notifications started.")
    case .failure:
        print("Failed to start real-time notifications.")
    }
    semaphore.signal()
}
semaphore.wait()

chatClient.register(event: .chatMessageReceived, handler: { response in
    switch response {
    case let .chatMessageReceivedEvent(event):
        print("Received a message: \(event.message)")
    default:
        return
    }
})

Atau, Anda dapat mengambil pesan obrolan dengan polling metode listMessages pada interval tertentu. Lihat cuplikan kode berikut untuk listMessages

chatThreadClient.listMessages { result, _ in
    switch result {
    case let .success(messagesResult):
        guard let messages = messagesResult.pageItems else {
            print("No messages returned.")
            return
        }

        for message in messages {
            print("Received message with id: \(message.id)")
        }

    case .failure:
        print("Failed to receive messages")
    }
    semaphore.signal()
}
semaphore.wait()

Menambahkan pengguna sebagai peserta ke utas obrolan

Setelah utas dibuat, Anda kemudian dapat menambahkan dan menghapus pengguna darinya. Dengan menambahkan pengguna, Anda memberi mereka akses untuk dapat mengirim pesan ke utas dan menambahkan/menghapus peserta lain. Sebelum menghubungi add, pastikan Anda telah memperoleh token akses dan identitas baru untuk pengguna tersebut. Pengguna akan membutuhkan token akses tersebut untuk menginisialisasi klien obrolan mereka.

Gunakan metode add dari ChatThreadClient untuk menambahkan satu atau beberapa peserta ke alur obrolan. Berikut ini adalah atribut yang didukung untuk setiap peserta utas:

  • id, wajib, adalah identitas peserta utas.
  • displayName, opsional, adalah nama tampilan untuk peserta utas.
  • shareHistoryTime, opsional, adalah waktu ketika riwayat obrolan dibagikan dengan peserta.

Ganti komentar <ADD A USER> dengan kode berikut:

let user = ChatParticipant(
    id: CommunicationUserIdentifier("<USER_ID>"),
    displayName: "Jane"
)

chatThreadClient.add(participants: [user]) { result, _ in
    switch result {
    case let .success(result):
        if let errors = result.invalidParticipants, !errors.isEmpty {
            print("Error adding participant")
        } else {
            print("Added participant")
        }
    case .failure:
        print("Failed to add the participant")
    }
    semaphore.signal()
}
semaphore.wait()

Ganti <USER_ID> dengan ID pengguna Azure Communication Services pengguna yang akan ditambahkan.

Mencantumkan Daftar pengguna di utas

Gunakan metode listParticipants untuk mendapatkan semua peserta untuk alur obrolan tertentu.

Ganti komentar <LIST USERS> dengan kode berikut:

chatThreadClient.listParticipants { result, _ in
    switch result {
    case let .success(participantsResult):
        guard let participants = participantsResult.pageItems else {
            print("No participants returned.")
            return
        }

        for participant in participants {
            let user = participant.id as! CommunicationUserIdentifier
            print("User with id: \(user.identifier)")
        }
    case .failure:
        print("Failed to list participants")
    }
    semaphore.signal()
}
semaphore.wait()

Jalankan kode

Pada Xcode tekan tombol Run untuk membangun dan menjalankan projek. Pada konsol Anda dapat melihat output dari kode dan pencatat output dari ChatClient.

Ingat: Atur Build Settings > Build Options > Enable Bitcode ke No. Saat ini AzureCommunicationChat SDK untuk iOS tidak mendukung pengaktifan bitcode, masalah GitHub berikut melacak ini.

Kode Sampel

Menemukan kode final untuk mulai cepat ini di GitHub.

Membersihkan sumber daya

Jika ingin membersihkan dan menghapus langganan Azure Communication Services, Anda bisa menghapus sumber daya atau grup sumber daya. Menghapus grup sumber daya juga menghapus sumber daya apa pun yang terkait dengannya. Pelajari lebih lanjut cara membersihkan sumber daya.

Langkah berikutnya

Dalam mulai cepat ini, Anda mempelajari cara:

  • Membuat klien obrolan
  • Membuat utas dengan dua pengguna
  • Mengirim pesan ke utas
  • Menerima pesan dari utas
  • Menghapus Pengguna dari utas

Mencoba Aplikasi Obrolan Hero

Anda mungkin juga ingin: