pusher_client

Pusher Channels Flutter Client

ปลั๊กอินไคลเอนต์ไคลเอนต์ Pusher สำหรับการกำหนดเป้าหมาย Android และ iOS มันห่อหุ้ม Websocket-Java v2.2.5 และ Pusher-Websocket-Swift v8.0.0

สำหรับการสอนและข้อมูลเชิงลึกเพิ่มเติมเกี่ยวกับช่องทางเร่งด่วนโปรดไปที่เอกสารอย่างเป็นทางการ

ไคลเอนต์นี้ทำงานร่วมกับเซิร์ฟเวอร์ Pusher อย่างเป็นทางการและ Laravel Hosted Websocket Server (Laravel-Websockets)

แพลตฟอร์มที่รองรับและเป้าหมายการปรับใช้

• Android API 16 ขึ้นไป
• iOS 9.0 ขึ้นไป

สารบัญ

• การติดตั้ง
• การกำหนดค่า
  • สำหรับ iOS
  • สำหรับ Android
• ภาพรวม API
• ตัวสร้างตัวเร่ง
• ตัวเลือกตัวเลือกการกำหนดค่า
• การเชื่อมต่อใหม่
• การตัดการเชื่อมต่อ
• สมัครรับข้อมูลช่อง
  • ช่องสาธารณะ
  • ช่องส่วนตัว
  • ช่องที่เข้ารหัสส่วนตัว
  • ช่องแสดง
• ผูกพันกับเหตุการณ์
  • พารามิเตอร์การโทรกลับ
  • เปิดเหตุการณ์ช่องทาง
• การเรียกเหตุการณ์ไคลเอนต์
• การเข้าถึงรหัสซ็อกเก็ตเชื่อมต่อ
• แก้ไขปัญหาทั่วไป

การติดตั้ง

เพิ่มไปยัง pubspec.yaml ของคุณ

 dependencies :
    pusher_client : ^2.0.0 

การกำหนดค่า

สำหรับ iOS

ตั้งค่าเป้าหมายการปรับใช้ขั้นต่ำใน PodFile เป็น 9.0 ไปที่ ios/Podfile จากนั้นยกเลิกการเขียนบทนี้:

 # platform :ios, '8.0'

เปลี่ยนเป็น:

 platform :ios, '9.0'

คุณอาจมีปัญหาที่สมัครรับช่องส่วนตัวหากคุณใช้เซิร์ฟเวอร์พุชเลอร์ในเครื่องเช่น Laravel-Websockets เพื่อแก้ไขปัญหานี้ไปที่ ios/Runner/Info.plist และเพิ่ม:

< key >NSAppTransportSecurity</ key >
< dict >
    < key >NSAllowsArbitraryLoads</ key >
    < true />
</ dict >

หากคุณรู้ว่าคุณจะเชื่อมต่อโดเมนใดเพื่อเพิ่ม:

< key >NSAppTransportSecurity</ key >
< dict >
    < key >NSExceptionDomains</ key >
    < dict >
        < key >example.com</ key >
        < dict >
            < key >NSExceptionAllowsInsecureHTTPLoads</ key >
            < true />
            < key >NSIncludesSubdomains</ key >
            < true />
        </ dict >
    </ dict >
</ dict >

สำหรับ Android

หากคุณเปิดใช้งานการทำให้งงงวยรหัสด้วย R8 หรือ Proguard คุณต้องเพิ่มกฎต่อไปนี้ใน android/app/build.gradle :

 buildTypes {
  release {
    minifyEnabled true
    proguardFiles getDefaultProguardFile( ' proguard-android.txt ' ), ' proguard-rules.pro '
  }
}

จากนั้นใน android/app/proguard-rules.pro :

 - keep class com.github.chinloyal.pusher_client .** { * ; } 

ภาพรวม API

นี่คือ API โดยสรุป

 PusherOptions options = PusherOptions (
    host : 'example.com' ,
    wsPort : 6001 ,
    encrypted : false ,
    auth : PusherAuth (
        'http://example.com/auth' ,
        headers : {
            'Authorization' : 'Bearer $ token ' ,
        },
    ),
);

PusherClient pusher = PusherClient (
    YOUR_APP_KEY ,
    options,
    autoConnect : false
);

// connect at a later time than at instantiation.
pusher. connect ();

pusher. onConnectionStateChange ((state) {
    print ( "previousState: ${ state . previousState }, currentState: ${ state . currentState }" );
});

pusher. onConnectionError ((error) {
    print ( "error: ${ error . message }" );
});

// Subscribe to a private channel
Channel channel = pusher. subscribe ( "private-orders" );

// Bind to listen for events called "order-status-updated" sent to "private-orders" channel
channel. bind ( "order-status-updated" , ( PusherEvent event) {
    print (event.data);
});

// Unsubscribe from channel
pusher. unsubscribe ( "private-orders" );

// Disconnect from pusher service
pusher. disconnect ();

ข้อมูลเพิ่มเติมในรูปแบบการอ้างอิงสามารถดูได้ด้านล่าง

ตัวสร้างตัวเร่ง

ตัวสร้างใช้คีย์แอปพลิเคชันซึ่งคุณสามารถรับได้จากส่วน API Access ของแอปในแผงควบคุมช่องสัญญาณ Pusher และวัตถุตัวเลือก Pusher

 PusherClient pusher = PusherClient ( YOUR_APP_KEY , PusherOptions ());

หากคุณกำลังจะใช้ช่องส่วนตัวการแสดงตนหรือช่องทางที่เข้ารหัสคุณจะต้องจัดเตรียม PusherAuth ที่จะใช้เมื่อตรวจสอบการสมัครรับข้อมูล ในการทำเช่นนี้คุณต้องผ่านวัตถุ PusherOptions ซึ่งมีชุด auth

 PusherAuth auth = PusherAuth (
    // for auth endpoint use full url
    'http://example.com/auth' ,
    headers : {
        'Authorization' : 'Bearer $ token ' ,
    },
);

PusherOptions options = PusherOptions (
    auth : auth
);

PusherClient pusher = PusherClient ( YOUR_APP_KEY , options);

เพื่อปิดการใช้งานการบันทึกและการเชื่อมต่ออัตโนมัติทำสิ่งนี้:

 PusherClient pusher = PusherClient (
    YOUR_APP_KEY ,
    options,
    enableLogging : false ,
    autoConnect : false ,
);

หากการเชื่อมต่ออัตโนมัติถูกปิดใช้งานคุณสามารถเชื่อมต่อด้วยตนเองโดยใช้ connect() บนอินสแตนซ์ของตัวผลักดัน

ตัวเลือกตัวเลือกการกำหนดค่า

ฟังก์ชันการทำงานส่วนใหญ่ของปลั๊กอินนี้ได้รับการกำหนดค่าผ่านวัตถุ pusheroptions คุณกำหนดค่าโดยการตั้งค่าพารามิเตอร์บนวัตถุก่อนที่จะส่งไปยังไคลเอนต์ Pusher ด้านล่างเป็นตารางที่มีคุณสมบัติทั้งหมดที่คุณสามารถตั้งค่าได้

วิธี	พารามิเตอร์	คำอธิบาย
ที่ได้เข้ารหัส	บูล	ไม่ว่าจะเป็นการเชื่อมต่อกับ TLS หรือไม่
รับรองความถูกต้อง	pusherauth	ตั้งค่าตัวเลือกการอนุญาตที่จะใช้เมื่อตรวจสอบช่องส่วนตัวการเข้ารหัสส่วนตัวและช่องทาง
เจ้าภาพ	สาย	โฮสต์ที่จะทำการเชื่อมต่อ
WSport	int	พอร์ตที่จะทำการเชื่อมต่อที่ไม่ได้เข้ารหัส ตั้งค่าอย่างถูกต้องโดยอัตโนมัติ
WSSPORT	int	พอร์ตที่จะทำการเชื่อมต่อที่เข้ารหัส ตั้งค่าอย่างถูกต้องโดยอัตโนมัติ
กลุ่ม	สาย	ตั้งค่าคลัสเตอร์ที่ไคลเอนต์จะเชื่อมต่อดังนั้นจึงตั้งค่าโฮสต์และพอร์ตให้ถูกต้อง
activitytimeout	int	จำนวนมิลลิวินาทีของการไม่ใช้งานที่ "ping" จะถูกกระตุ้นให้ตรวจสอบการเชื่อมต่อ ค่าเริ่มต้นคือ 120,000
pongtimeout	int	จำนวนมิลลิวินาทีที่ไคลเอนต์รอที่จะได้รับการตอบกลับ "พงษ์" จากเซิร์ฟเวอร์ก่อนที่จะตัดการเชื่อมต่อ ค่าเริ่มต้นคือ 30,000
MaxReconnectionAttempts	int	จำนวนความพยายามในการเชื่อมต่อใหม่ที่จะเกิดขึ้นเมื่อเรียกว่า pusher.connect() หลังจากนั้นลูกค้าจะยอมแพ้
MaxReconnectGapinseconds	int	ความล่าช้าในการเชื่อมต่อสองครั้งขยายแบบทวีคูณ (1, 2, 4, .. วินาที) คุณสมบัตินี้ตั้งค่าสูงสุดระหว่างการเชื่อมต่อสองครั้ง

การเชื่อมต่อใหม่

วิธี connect() ยังใช้ในการเชื่อมต่ออีกครั้งในกรณีที่การเชื่อมต่อหายไปเช่นหากอุปกรณ์สูญเสียการรับสัญญาณ โปรดทราบว่าสถานะของการสมัครสมาชิกช่องและการผูกเหตุการณ์จะถูกเก็บรักษาไว้ในขณะที่ตัดการเชื่อมต่อและเจรจาต่อรองกับเซิร์ฟเวอร์อีกครั้งเมื่อการเชื่อมต่อถูกสร้างขึ้นใหม่

การตัดการเชื่อมต่อ

pusher. disconnect ();

หลังจากยกเลิกการเชื่อมต่ออินสแตนซ์ PusherClient จะปล่อยทรัพยากรที่จัดสรรภายใน (เธรดและการเชื่อมต่อเครือข่าย)

สมัครรับข้อมูลช่อง

ช่องทางใช้แนวคิดของช่องเป็นวิธีการสมัครรับข้อมูล พวกเขาจะถูกระบุและสมัครสมาชิกด้วยชื่อง่าย ๆ เหตุการณ์ถูกผูกไว้กับช่องและถูกระบุด้วยชื่อ

ดังที่ได้กล่าวไว้ข้างต้นการสมัครรับข้อมูลช่องจะต้องลงทะเบียนเพียงครั้งเดียวโดยอินสแตนซ์ PusherClient พวกเขาจะได้รับการเก็บรักษาไว้ในการขาดการเชื่อมต่อและสร้างใหม่ด้วยเซิร์ฟเวอร์บนการเชื่อมต่ออีกครั้ง พวกเขาไม่ควรลงทะเบียนอีกครั้ง อย่างไรก็ตามพวกเขาอาจลงทะเบียนด้วยอินสแตนซ์ PusherClient ก่อนการโทรครั้งแรกเพื่อ connect - พวกเขาจะเสร็จสิ้นด้วยเซิร์ฟเวอร์ทันทีที่มีการเชื่อมต่อพร้อมใช้งาน

ช่องสาธารณะ

วิธีการเริ่มต้นสำหรับการสมัครสมาชิกช่องเกี่ยวข้องกับการเรียกใช้วิธีการสมัครสมาชิกของวัตถุไคลเอนต์ของคุณ:

 Channel channel = pusher. subscribe ( "my-channel" );

สิ่งนี้จะส่งคืนวัตถุ Channel ซึ่งเหตุการณ์ใดที่สามารถผูกมัดได้

ช่องส่วนตัว

ช่องส่วนตัวถูกสร้างขึ้นในลักษณะเดียวกับช่องทางสาธารณะยกเว้นว่าพวกเขาอาศัยอยู่ในเนมสเปซ 'ส่วนตัว-' นี่หมายถึงคำนำหน้าชื่อช่อง:

 Channel privateChannel = pusher. subscribe ( "private-status-update" );

การสมัครรับข้อมูลช่องส่วนตัวเกี่ยวข้องกับลูกค้าที่ได้รับการรับรองความถูกต้อง ดูที่ส่วนของตัวสร้างตัวสร้างสำหรับตัวอย่างช่องทางที่ได้รับการรับรองความถูกต้องสำหรับข้อมูลเพิ่มเติม

ช่องที่เข้ารหัสส่วนตัว

เช่นเดียวกับช่องส่วนตัวคุณยังสามารถสมัครรับข้อมูลช่องทางที่เข้ารหัสส่วนตัวได้ ปลั๊กอินนี้รองรับการเข้ารหัสแบบ end-to-end อย่างเต็มที่ ซึ่งหมายความว่ามีเพียงคุณและลูกค้าที่เชื่อมต่อของคุณเท่านั้นที่จะสามารถอ่านข้อความของคุณได้ Pusher ไม่สามารถถอดรหัสได้ ช่องเหล่านี้จะต้องนำหน้าด้วย 'การเข้ารหัสส่วนตัว-'

เช่นเดียวกับช่องส่วนตัวคุณต้องให้จุดสิ้นสุดการรับรองความถูกต้อง จุดสิ้นสุดนั้นจะต้องใช้ไคลเอนต์เซิร์ฟเวอร์ที่รองรับการเข้ารหัสแบบ end-to-end มีจุดสิ้นสุดการสาธิตให้ดูโดยใช้ nodejs

ช่องแสดง

ช่องแสดงเป็นช่องที่มีชื่อนำหน้าโดย 'สถานะ-' ช่องแสดงสถานะยังต้องได้รับการรับรองความถูกต้อง

 Channel presenceChannel = pusher. subscribe ( "presence-another-channel" );

ผูกพันกับเหตุการณ์

มีเหตุการณ์สองประเภทที่เกิดขึ้นในการสมัครสมาชิกช่อง

1. เหตุการณ์ที่เกี่ยวข้องกับโปรโตคอลเช่นเหตุการณ์ที่เกิดขึ้นเมื่อการสมัครสมาชิกสำเร็จตัวอย่างเช่น "pusher: subscription_succeeded"
2. กิจกรรมแอปพลิเคชันที่ถูกเรียกใช้รหัสภายในแอปของคุณ

 Channel channel = pusher. subscribe ( "private-orders" );

channel. bind ( "order-status-updated" , ( PusherEvent event) {
    print (event.data);
});

พารามิเตอร์การโทรกลับ

การโทรกลับที่คุณผูกจะได้รับ PusherEvent :

คุณสมบัติ	พิมพ์	คำอธิบาย
eventName	String	ชื่อของเหตุการณ์
channelName	String	ชื่อของช่องทางที่เหตุการณ์ถูกเรียกใช้ (ไม่จำเป็น)
data	String	ข้อมูลที่ส่งผ่านไปยัง trigger เข้ารหัสเป็นสตริง หากคุณผ่านวัตถุนั้นจะได้รับการจัดลำดับไปยังสตริง JSON ซึ่งคุณสามารถแยกวิเคราะห์ได้ตามความจำเป็น (ไม่จำเป็น)
userId	String	ID ของผู้ใช้ที่เรียกเหตุการณ์ สิ่งนี้มีให้เฉพาะสำหรับเหตุการณ์ไคลเอนต์ที่ทริกเกอร์ในช่องสถานะ (ไม่จำเป็น)

เปิดเหตุการณ์ช่องทาง

คุณสามารถยกเลิกเหตุการณ์ได้โดยการทำ:

channel. unbind ( "order-status-updated" );

การเรียกเหตุการณ์ไคลเอนต์

เมื่อการสมัครสมาชิกส่วนตัวหรือการแสดงตนได้รับอนุญาตและการสมัครสมาชิกประสบความสำเร็จเป็นไปได้ที่จะกระตุ้นเหตุการณ์ในช่องเหล่านั้น

เหตุการณ์ที่เกิดขึ้นจากลูกค้าเรียกว่ากิจกรรมของลูกค้า เนื่องจากพวกเขากำลังถูกกระตุ้นจากลูกค้าซึ่งอาจไม่เชื่อถือได้จึงมีกฎที่บังคับใช้จำนวนมากเมื่อใช้งาน กฎเหล่านี้บางส่วนรวมถึง:

• ชื่อเหตุการณ์ต้องมีคำนำหน้า 'ไคลเอนต์-'
• ขีด จำกัด อัตรา
• คุณสามารถเรียกเหตุการณ์เมื่อการสมัครสมาชิกสำเร็จเท่านั้น

channel. bind ( "pusher:subscription_succeeded" , ( PusherEvent event) {
    channel. trigger ( "client-istyping" , { "name" : "Bob" });
});

สำหรับรายละเอียดทั้งหมดดูเอกสารเหตุการณ์ของลูกค้า

การเข้าถึงรหัสซ็อกเก็ตเชื่อมต่อ

เมื่อเชื่อมต่อคุณสามารถเข้าถึงตัวระบุที่ไม่ซ้ำกันสำหรับการเชื่อมต่อของไคลเอนต์ปัจจุบัน สิ่งนี้เรียกว่า รหัสซ็อกเก็ ต คุณสามารถเข้าถึงค่าได้เมื่อการเชื่อมต่อได้รับการจัดตั้งขึ้นดังนี้:

 String socketId = pusher. getSocketId ();

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับวิธีการและเหตุผลที่มีซ็อกเก็ตรหัสดูเอกสารเกี่ยวกับการตรวจสอบสิทธิ์ผู้ใช้และไม่รวมผู้รับ

แก้ไขปัญหาทั่วไป

iOS ไม่ได้บันทึกเมื่อ enableLogging ถูกตั้งค่าเป็นจริง

การบันทึก iOS ดูเหมือนจะไม่ส่งออกไปยังคอนโซล Flutter แต่ถ้าคุณเรียกใช้แอพจาก XCode คุณควรจะเห็นบันทึก

สมัครสมาชิกช่องส่วนตัวด้วย iOS

หากใช้เซิร์ฟเวอร์พุชเลอร์ในพื้นที่ แต่ไม่สามารถสมัครสมาชิกช่องส่วนตัวได้ให้เพิ่มสิ่งนี้ลงใน iOS/runner/info.plist ของคุณ:

< key >NSAppTransportSecurity</ key >
< dict >
    < key >NSAllowsArbitraryLoads</ key >
    < true />
</ dict >

หากคุณรู้ว่าคุณจะเชื่อมต่อโดเมนใดเพื่อเพิ่ม:

< key >NSAppTransportSecurity</ key >
< dict >
    < key >NSExceptionDomains</ key >
    < dict >
        < key >example.com</ key >
        < dict >
            < key >NSExceptionAllowsInsecureHTTPLoads</ key >
            < true />
            < key >NSIncludesSubdomains</ key >
            < true />
        </ dict >
    </ dict >
</ dict >