Skip to main content
Widget Ayrshare Connect đặt các nút liên kết của chúng tôi bên trong dashboard của riêng bạn. Bạn tải một script, thả một slot vào bất cứ nơi nào một mạng thuộc về trong bố cục của bạn, và chúng tôi render một nút ở đó đã hiển thị sẵn tài khoản đã được kết nối hay chưa. Người dùng của bạn nhấp vào nó và liên kết tài khoản mà không rời khỏi trang của bạn — nhiều nhất một cửa sổ bật lên, là của chính mạng xã hội. Bạn không phải viết xử lý cửa sổ bật lên, không có OAuth callback, không có làm mới phiên, và không có logic theo từng mạng. Khi một mạng thay đổi điều gì đó ở phía họ, bản sửa lỗi được đưa vào bên trong các khung của chúng tôi ngay khi chúng tôi triển khai; bạn không phải triển khai lại gì cả.

Bạn Muốn Bề mặt Nào

Một dashboard khách hàng với các thẻ Ayrshare Connect cho Instagram, TikTok và LinkedIn được nhúng trong một card

Khung nhúng: các thẻ của chúng tôi được render bên trong bố cục của riêng bạn, một slot cho mỗi mạng hoặc một slot cho nhiều mạng.

Một dashboard khách hàng với các nút Connect của riêng nó và một cửa sổ bật lên Ayrshare hiển thị màn hình chuyển giao của Facebook

Nút của riêng bạn: bạn render nút, và một cửa sổ bật lên ngắn của chúng tôi xử lý mạng xã hội.

Trang liên kết mạng xã hội được lưu trữ hiển thị mọi mạng khả dụng

Trang liên kết được lưu trữ: một trang do chúng tôi lưu trữ, mang logo và màu sắc của bạn, mà người dùng của bạn rời khỏi ứng dụng của bạn để dùng.

Hai hàng widget là một tích hợp, không phải hai. Một lần init duy nhất cho bạn cả hai: gắn các khung ở nơi bạn muốn có nút của chúng tôi, và gọi popup() từ nút của riêng bạn ở mọi nơi khác. Chúng dùng chung một phiên và báo cáo trên cùng các handler.Chế độ trực tiếp (Direct Mode) là cùng cửa sổ bật lên đó nhưng không có script của chúng tôi — dành cho trang có Content-Security-Policy nghiêm ngặt, trang render phía máy chủ, hoặc ứng dụng gốc. Ở đó bạn tự mở và tự theo dõi cửa sổ bật lên.

Thêm Script

Ghim một phiên bản cùng hash của nó, hoặc theo một channel mà không có hash. Đừng bao giờ dùng cả hai — một thuộc tính integrity trên một URL di động sẽ ngừng hoạt động ở lần phát hành tiếp theo của chúng tôi, vì tệp mà nó chỉ định đã thay đổi một cách hợp lệ.
Pinned version
Tracking v1
v1 là channel nên khuyến nghị. Nó nhận các bản sửa lỗi nhưng không bao giờ vượt qua một thay đổi phá vỡ tương thích. latest theo định nghĩa sẽ vượt qua các phiên bản major, nên đến một lúc nào đó nó sẽ đưa cho trang của bạn một phiên bản mà bạn chưa xem xét hành vi. Hash của mọi phiên bản được công bố trong manifest.json, tệp này cũng nêu rõ mỗi channel hiện đang phục vụ phiên bản nào:
manifest.json
Mỗi bundle cũng mở đầu bằng một comment nêu phiên bản của chính nó, là cách nhanh nhất để cho chúng tôi biết một trang thực sự đang chạy phiên bản nào:

Content-Security-Policy

Nếu trang của bạn gửi Content-Security-Policy, nó cần hai mục, cả hai đều nêu host mà bạn tải script từ đó:
Đó là toàn bộ danh sách. Bạn không cần mục connect-src cho chúng tôi — các khung của chúng tôi truy cập API của chúng tôi từ bên trong chính chúng, không phải từ trang của bạn — và không cần mục nào cho cửa sổ bật lên, vốn là các cửa sổ cấp cao nhất mà chính sách của bạn không kiểm soát. Cả hai mục đều đã được đo lường: bỏ script-src sẽ chặn script, và bỏ frame-src sẽ chặn khung.

Khởi động một Instance

session là tùy chọn bắt buộc duy nhất. Nó được gọi một lần cho mỗi instance, không phải một lần cho mỗi mount, và phải trả về phản hồi của backend của bạn từ Tạo một Link Session với mode: "connect" — { sessionId, token, expiresAt } — đúng như khi nó được trả về.
Your page
Your backend
Một phiên widget không nêu network nào — nó cấp quyền cho mọi mạng mà tài khoản của bạn cho phép, và mạng nào xuất hiện được quyết định theo từng mount, trong trang của bạn. Nó mang theo một origin, và đó là điều duy nhất khiến các khung render được: một khung kiểm tra trang đang nhúng nó với giá trị đó và từ chối render ở bất kỳ nơi nào khác.
Hãy tạo phiên trên máy chủ của bạn. Lệnh gọi cần API key của bạn, và token nó trả về sẽ đăng nhập người dùng của bạn vào User Profile của họ — hãy coi nó như một mật khẩu.
Chúng tôi gọi lại session trước khi token hết hạn, nên widget tiếp tục hoạt động trên một trang được mở cả ngày. Một lệnh gọi bị reject, hoặc không trả về token, được thử lại hai lần nữa — sau 0,5 giây, rồi 1 giây — trước khi chúng tôi bỏ cuộc và phát ra error. Vì vậy một lần làm mới tốn nhiều nhất ba lệnh gọi đến endpoint của bạn.

Gắn một Slot

Một mount cho mỗi slot. Yêu cầu một mạng, vài mạng, hoặc mọi thứ mà phiên cho phép — mức độ chi tiết là của bạn, nên một slot có thể là một hàng đơn trong một bảng có sẵn hoặc một panel chứa tất cả.
mount nhận một CSS selector hoặc một element, và trả về { unmount, element }. Nó throw nếu target không khớp gì cả — mà hầu như luôn là một slot chưa tồn tại, vì vậy hãy mount sau khi markup của bạn đã có trong document. Mỗi mount là một iframe. Nó báo cáo chiều cao của chính nó cho chúng tôi và chúng tôi thay đổi kích thước để khớp, nên bố cục của bạn tự sắp xếp lại khi nội dung của chúng tôi thay đổi; vượt quá maxHeight, khung tự cuộn bên trong thay vì tràn ra khỏi trang của bạn. Slot hẹp nhất chúng tôi hỗ trợ là 300px. Các khóa mạng là của chính Ayrshare, và các cách viết bí danh cũng hoạt động: instagram và instagramapi đều có nghĩa là instagramApi, và x có nghĩa là twitter. Một khóa không phải là một mạng sẽ không render thẻ nào.

Nút của Riêng Bạn

Một khách hàng muốn dùng nút của riêng họ thay vì một trong các khung của chúng tôi sẽ gọi popup thay thế. Nó chạy cùng một luồng, trên cùng một phiên, và báo cáo trên cùng các handler.
Hãy gọi nó trực tiếp bên trong click handler, không await gì trước nó. Trình duyệt chỉ cho phép một cửa sổ bật lên trong khi nó vẫn đang xử lý cú nhấp của người dùng, và quyền đó không sống sót qua một await. Dù sao cũng không có gì cần await — phiên đã được tạo lúc init.
popup trả về { close(), network }, và luôn luôn trả về một handle — kể cả sau một cửa sổ bật lên bị chặn, khi đó close() không làm gì — nên mã của bạn không bao giờ phải null-check nó trước khi gọi close(). Mọi mạng đều hoạt động ở đây, kể cả những mạng mà một khung hoàn tất bên trong panel của chính nó: Facebook hiển thị màn hình giải thích chuyển giao của nó trong cửa sổ bật lên, Bluesky và X hiển thị form thông tin xác thực của chúng, còn LinkedIn, Pinterest, YouTube và Google Business đi ra mạng xã hội rồi quay lại. Nó throw một cách đồng bộ với ba điều là lỗi lập trình — không có network, một instance đã bị destroy, hoặc một phiên chưa resolve. Một cửa sổ bật lên bị chặn không phải một trong số đó: điều đó phát ra error với reason: "popupBlocked", vì người dùng của bạn không làm gì sai. Nhiều nhất một cửa sổ bật lên được mở tại một thời điểm. Lệnh gọi thứ hai đóng cửa sổ thứ nhất và báo cáo cancelled với reason: "superseded" trên nó. Một cửa sổ bật lên do một trong các khung của chúng tôi mở là một thứ khác và không bao giờ bị đụng đến, nên nút của bạn không thể hủy một luồng đang chạy bên trong một slot đã mount.
Việc phiên có được phép liên kết một mạng hay không là câu trả lời của máy chủ, không phải của script. Một phiên được giới hạn cho Bluesky mà được yêu cầu LinkedIn sẽ nhận được một sự từ chối hiển thị trong cửa sổ bật lên và được báo cáo dưới dạng error. Script chỉ kiểm tra rằng một mạng đã được nêu tên.

React

Script không phụ thuộc framework, nên React không cần gì đặc biệt từ chúng tôi — nhưng bốn điều về vòng đời của nó đáng làm đúng ngay từ lần đầu. Tải script một lần, bên ngoài cây component của bạn. Trong Next.js đó là next/script trong root layout của bạn; trong Vite hoặc Create React App đó là một thẻ trong index.html. Tải nó theo từng component sẽ chạy lại nó ở mỗi lần mount.
ConnectAccounts.jsx
Không bao giờ dùng lại một instance sau destroy(). Một instance đã bị destroy sẽ vẫn bị destroy — popup() throw trên nó, và mount() sẽ không đưa nó trở lại. Hãy tạo một instance mới trong lần chạy effect tiếp theo, đó chính là điều đoạn mã trên làm.
Hai hệ quả của mẫu đó, và cả hai đều không phải bug:
  • Trong môi trường phát triển bạn sẽ thấy callback session được gọi hai lần. Strict Mode của React chạy các effect theo trình tự mount → unmount → mount, nên instance được tạo, bị destroy và được tạo lại. Phần cleanup ở trên làm cho điều đó an toàn; nó tốn thêm một lệnh gọi đến backend của bạn trong dev và không tốn gì trong production.
  • Giữ các dependency của effect ổn định. Một array literal được truyền thẳng vào mount từ một lần render của component cha là một giá trị mới mỗi lần, nên một effect phụ thuộc vào nó sẽ gỡ widget xuống và dựng lại nó ở mỗi lần render. Hãy memoize nó, hoặc giữ nó là hằng số như ở trên.

Sự kiện

Đăng ký với on, hàm này trả về một hàm hủy đăng ký. Các handler nhận payload của sự kiện và mount mà nó đến từ; off(name, handler) làm cùng công việc khi bạn muốn đặt tên cho handler.
Mười sự kiện. Mọi sự kiện đều mang một network ngoại trừ ready, và ngoại trừ loại error duy nhất hoàn toàn không liên quan đến một mạng — xem error có hai nguồn bên dưới. Bốn trong số đó là kết cục — success, unlinked, error và cancelled — và đúng một trong số chúng đến cho mỗi lần thử. closed là một thông báo vòng đời đi theo sau một kết cục chứ không phải là một kết cục. click phát ra trước khi bất kỳ công việc liên kết nào bắt đầu, nên nó báo cáo một cú nhấp mà một cửa sổ bật lên bị chặn hoặc một phiên đã chết sau đó từ chối. Đây là sự kiện để dùng cho analytics của riêng bạn; started mới là sự kiện có nghĩa là một lần thử thực sự đang chạy.

Reasons

error Có Hai Nguồn

Chỉ một trong hai là thất bại liên kết, và chúng mang các trường khác nhau.
  • Một lỗi liên kết mang network, code và mount mà nó đến từ.
  • Một lỗi phiên — chúng tôi không thể tạo hoặc làm mới phiên của bạn — chỉ mang message, vì không có gì đang được liên kết vào lúc đó.
Hãy destructure một cách phòng thủ: code và network là undefined ở loại thứ hai.

state Giúp Bạn Khỏi Polling

state là kênh dữ liệu chứ không phải báo cáo về một lần thử. Mỗi khung phát ra một sự kiện cho mỗi mạng khi nó mount, mang trạng thái hiện tại của mạng đó và mốc thời gian since mà nó giữ trạng thái đó từ đó, và một sự kiện nữa mỗi khi một trạng thái thay đổi — bao gồm cả các thay đổi bắt nguồn từ phía chúng tôi, chẳng hạn một token chết chuyển sang trạng thái cần liên kết lại. Vì vậy bạn có thể vận hành toàn bộ UI của mình từ widget mà không phải polling bất cứ thứ gì. Các giá trị là cùng một enum mà GET /profiles với include=state trả về: linked, unlinked, identityVerificationRequired, restricted, rateLimited, suspended.

Hủy liên kết

Các thẻ của chúng tôi hủy liên kết cũng như liên kết. Người dùng của bạn nhấp vào một mạng đã kết nối, xác nhận, và tài khoản được gỡ:
  1. click phát ra với action: "unlink".
  2. unlinked phát ra khi việc gỡ đã được lưu.
Một lần hủy liên kết thất bại báo cáo error, và một lần mà người dùng của bạn rút lui ở bước xác nhận báo cáo cancelled. Không có sự kiện hủy-liên-kết-thất-bại riêng.

Giao diện

Stylesheet của khách hàng không thể chạm vào bên trong một khung cross-origin, nên việc tạo kiểu được truyền dưới dạng dữ liệu mà chúng tôi áp dụng bên trong nó. Truyền appearance cho init dưới dạng các CSS custom property; mỗi property chúng tôi không nhận được sẽ giữ giá trị mặc định của chúng tôi.
Hãy đặt màu theo cặp. Một token nền không có token chữ đi kèm là cách duy nhất làm cho thứ này tạo ra thứ gì đó không đọc được: đặt riêng --ayr-connect-surface-bg thành một giá trị tối và --ayr-connect-surface-fg mặc định của chúng tôi vẫn là màu xanh navy tối. Không gì có thể suy ra nửa còn lại giúp bạn.
Khi hoàn toàn không có appearance, mọi token giữ giá trị mặc định và một khung trông như thế này:
Ba thẻ Ayrshare Connect với giao diện mặc định

Các token mặc định: bề mặt trắng, chữ xanh navy tối, màu nhấn indigo, bo góc 8px.

Truyền một vài token và cùng khung đó khoác lên bảng màu của bạn. Ví dụ này chuyển các bề mặt sang xanh nhạt, làm đậm chữ và màu nhấn cho tương xứng, và bo góc thêm một chút:
Ba thẻ Ayrshare Connect được tạo kiểu lại với bề mặt xanh nhạt và màu nhấn xanh đậm hơn

Cùng ba thẻ đó sau khi các token ở trên được áp dụng.

Chỉ có một bảng màu và không có preset sáng/tối. Không có gì phụ thuộc vào prefers-color-scheme, một cách có chủ đích — chủ đề của trang bạn có thể không khớp với hệ điều hành của người dùng, và một media query sẽ âm thầm lấn át các màu bạn đã chọn. Một dashboard tối được tạo chủ đề bằng cách cung cấp các giá trị tối. Danh sách token này là một hợp đồng được hỗ trợ mà chúng tôi giữ nguyên qua các phiên bản.

Các Token

Một giá trị không phải CSS hợp lệ cho token của nó sẽ bị bỏ qua, kèm một cảnh báo trong console của bạn, thay vì được áp dụng. Điều đó quan trọng hơn nghe có vẻ: một số 8 không đơn vị cho --ayr-connect-spacing là một chuỗi hoàn toàn vô hại nhưng sẽ làm mất hiệu lực mọi phép tính đọc nó và làm sụp đổ bố cục, mà không có lỗi ở đâu cả. Hãy cho các độ dài một đơn vị.

Tên Của Riêng Bạn Trên Màn hình Chuyển giao

Trước khi chúng tôi chuyển người dùng của bạn sang một mạng, chúng tôi hiển thị một màn hình ngắn nêu tên họ đang kết nối thông qua ai. Hai hook cho phép bạn biến nó thành của riêng mình, và cả hai đều ổn định qua các phiên bản. --ayr-connect-partner-name đặt nhãn. Đây là token duy nhất mà giá trị của nó là văn bản, nên nó phải được đặt trong dấu nháy như một chuỗi CSS — một giá trị không có dấu nháy là không hợp lệ và hoàn toàn không render gì:
Logo không phải là một token. Chúng tôi cung cấp phần đánh dấu dưới dạng một element đã được định vị và định kích thước, và bạn lấp đầy nó bằng một background-image thông qua css, như ở trên — một token có thể tải một hình ảnh từ bên trong document của chúng tôi không phải là thứ chúng tôi chấp nhận, nên yêu cầu đến từ một rule bạn viết chứ không phải từ một giá trị bạn truyền cho chúng tôi.
[data-ayr-connect-partner-mark] và [data-ayr-connect-partner-name] là ngoại lệ của lưu ý về CSS tùy chỉnh bên dưới: hai selector này là một phần của hợp đồng và chúng tôi giữ chúng qua các phiên bản.

CSS Tùy chỉnh

css nhận một chuỗi được áp dụng bên trong mọi khung, cho các trường hợp mà token không bao phủ.
CSS tùy chỉnh không được hỗ trợ qua các phiên bản. Các selector của nó nhắm vào markup nội bộ của chúng tôi, thứ thay đổi giữa các bản phát hành — một rule hoạt động hôm nay có thể âm thầm ngừng khớp sau bất kỳ bản cập nhật nào. Hợp đồng token ở trên là phần chúng tôi giữ. Hãy ghim một phiên bản nếu bạn phụ thuộc vào CSS tùy chỉnh.
Các cửa sổ bật lên kế thừa appearance và css của instance đúng như các khung, nên người dùng của bạn không phải nhìn thấy các giá trị mặc định trung tính của chúng tôi xuất hiện giữa chừng một luồng.

Đáng Biết Trước Khi Bạn Phát hành

Một cửa sổ bật lên bạn mở bằng popup() không thể được cho biết vì sao một token bị từ chối — để nói ra điều đó nó sẽ phải tin một origin mà nó chưa xác thực, điều mà mô hình bảo mật của chúng tôi không cho phép. Vì vậy một cửa sổ bật lên mang một token đã chết sẽ đóng lại và hiện ra dưới dạng cancelled với reason: "popupClosed" thay vì error.Trên thực tế điều này hiếm: một cửa sổ bật lên được mở trước một lần làm mới âm thầm vẫn tiếp tục hoạt động, vì nó đã xác thực token của nó khi mở. Nếu bạn thấy các kết quả popupClosed không giải thích được, hãy kiểm tra rằng endpoint session của bạn đang trả về một phiên mới.
Mười bốn mount dùng chung một token và tốn một lệnh gọi đến backend của bạn, không phải mười bốn. Nếu bạn muốn các slot có phạm vi khác nhau — một allowedSocial khác trên một số slot — hãy chạy một init thứ hai với phiên riêng của nó thay vì kỳ vọng một mount thu hẹp nó.
Mỗi phiên mang origin mà trang của bạn chạy trên đó, và một khung so sánh trang đang nhúng nó với giá trị đó trước khi render bất cứ thứ gì. Một khung được nhúng ở nơi khác sẽ trống và không gửi sự kiện nào. Không có allowlist để đăng ký và không có gì để cấu hình — hãy gửi đúng origin khi bạn tạo phiên.
Các khung báo cáo chiều cao của chúng cho script, và script thay đổi kích thước chúng. Bố cục của bạn chỉ việc sắp xếp lại. Không có sự kiện resize nào để đăng ký, và không có gì để đo ở phía bạn.

Yêu cầu

  • Max Pack. Một phiên widget là một phiên chế độ connect, và tạo một phiên như vậy mà không có Max Pack trả về code: 504. Hãy liên hệ bộ phận hỗ trợ nếu bạn cần bật chế độ connect trên một tài khoản không có nó.
  • Một origin trên mỗi phiên — origin chính xác mà trang của bạn chạy trên đó. Bỏ qua nó trả về code: 505; một giá trị không phải là một origin https, một custom scheme, hoặc http://localhost trả về code: 506.
  • Không có network trên phiên. Tham số đó là thứ biến một phiên thành chế độ trực tiếp, và URL của một phiên chế độ trực tiếp không phải là thứ script mong đợi.
Mọi mã ở trên đều có trong tài liệu tham khảo Lỗi Link Session, kèm thông báo chính xác mà API trả về và việc cần làm với nó.