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

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.

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 đượ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.
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ínhintegrity 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ệ.
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:
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ừ đó: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ề.
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.
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ộtmount 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ọipopup
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.
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.
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.
- 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
mounttừ 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ớion, 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.
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.
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,codevà 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 đó.
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ỡ:clickphát ra vớiaction: "unlink".unlinkedphát ra khi việc gỡ đã được lưu.
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ềnappearance 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.
appearance, mọi token giữ giá trị mặc định và một khung trông như thế
này:

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.

Cùng ba thẻ đó sau khi các token ở trên được áp dụng.
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
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ì:
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ủ.
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 có phiên đã hết hạn báo cáo cancelled, không phải error
Một cửa sổ bật lên có phiên đã hết hạn báo cáo cancelled, không phải error
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ột phiên cho mỗi instance, không phải một phiên cho mỗi mount
Một phiên cho mỗi instance, không phải một phiên cho mỗi mount
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ó.Các khung chỉ render trên origin bạn đã khai báo
Các khung chỉ render trên origin bạn đã khai báo
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.Chiều cao được xử lý giúp bạn, và không phải là một sự kiện
Chiều cao được xử lý giúp bạn, và không phải là một sự kiệ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
origintrê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 originhttps, một custom scheme, hoặchttp://localhosttrả vềcode: 506. - Không có
networktrê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.