Skip to main content
Người dùng của bạn tự kết nối các tài khoản mạng xã hội của chính họ — họ xác thực trực tiếp với từng mạng, và bạn không bao giờ thấy hay lưu trữ thông tin đăng nhập của họ. Mọi thứ trên trang này là về việc đưa họ đến khoảnh khắc đó và tìm hiểu kết quả ra sao. Có một điều chung cho mọi lộ trình: một phiên liên kết (link session), được tạo bằng Tạo một Link Session từ API key của bạn và một Profile-Key. Không có gì được ký ở phía bạn và không có private key nào trong luồng.

Ba cách Kết nối

Ba hình thức, và hai hình thức đầu là cùng một tích hợp. Hãy chọn theo từng luồng — chúng không loại trừ lẫn nhau, và rất nhiều tích hợp dùng trang liên kết được lưu trữ cho onboarding và dùng widget bên trong ứng dụng sau đó.
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.Chưa chắc chọn gì? Hãy bắt đầu với trang liên kết được lưu trữ. Nó không cần Max Pack và không cần tham số bổ sung, và là lộ trình nhanh nhất để có thứ gì đó hoạt động — chuyển sang widget sau này không thay đổi cách các phiên được tạo.

Tạo một Liên kết

Gọi Tạo một Link Session với Profile-Key của người dùng trong header. Với trang liên kết được lưu trữ, đó là toàn bộ yêu cầu:
cURL
Bạn nhận lại một url mang theo một token không minh bạch, có thời hạn ngắn:
Linking URL
Bạn cũng có thể kiểm tra xem một liên kết đã được mở chưa và thu hồi nó trước khi hết hạn.
Video 1 phút này hướng dẫn việc tạo một liên kết. Video được ghi trước khi có link sessions, nên vẫn cho thấy việc gửi Private Key — bước đó không còn cần thiết, và mọi thứ khác trong video vẫn không thay đổi.

Gửi URL liên kết

URL liên kết sẽ đăng nhập người dùng của bạn vào profile của họ, nên hãy coi nó như một mật khẩu. Gửi qua kênh mà bạn tin cậy, không ghi vào log và không chuyển cho bên thứ ba. Nó vẫn dùng được trong suốt khoảng thời gian hiệu lực, nên tải lại hay thử lại OAuth đều được — nhưng chỉ gửi mỗi liên kết cho một người dùng, và tạo liên kết riêng cho từng người.

Mở URL liên kết

Mở nó trong một tab trình duyệt mới, cửa sổ mới, hoặc view controller. Bạn có thể kiểm soát việc đóng hoặc chuyển hướng của cửa sổ đó.
Các mạng xã hội không cho phép mở trang liên kết được lưu trữ bên trong iFrame, hoặc che giấu origin đối tác đã được phê duyệt profile.ayrshare.com. Nếu bạn muốn việc liên kết diễn ra bên trong trang của riêng bạn, đó chính là mục đích của widget nhúng: các khung của nó được phục vụ từ một origin của Ayrshare và là cách được hỗ trợ để làm điều đó.

Biết Khi nào Hoàn tất

Hai tín hiệu, và bạn có thể dùng tín hiệu nào cũng được:
  • Sự kiện hoàn tất liên kết — đặt một origin khi bạn tạo liên kết và cửa sổ liên kết sẽ gửi connect:success, connect:error và connect:cancelled đến trang của bạn ngay khi chúng xảy ra. Không cần polling.
  • Lấy một Link Session — báo cáo completedAt, lastCompletedAt và completedNetworks. Đây là tín hiệu cho ứng dụng gốc, và là tín hiệu duy nhất cho Telegram, vốn hoàn tất ngoài luồng.

Thời hạn Liên kết

Một liên kết có hiệu lực trong 5 phút theo mặc định. Sau đó, hãy tạo liên kết mới. Với Max Pack, hãy đặt expiresIn tính bằng phút để mở rộng khoảng thời gian đó — tối đa 2880 phút (48 giờ), là mức tối đa API chấp nhận:
Expires In
Khoảng thời gian dài hơn là điều làm cho việc gửi liên kết qua email trở nên thực tế — một người dùng kết nối lại tài khoản bị rớt có thể đi thẳng từ email của bạn đến mạng xã hội, mà không cần vào ứng dụng của bạn trước.
Hãy xem xét với đội bảo mật của bạn về việc một liên kết nên tồn tại bao lâu. Khoảng thời gian dài hơn là khoảng thời gian dài hơn mà một liên kết bị chặn bắt vẫn hoạt động. Nếu một liên kết lọt ra ngoài, bạn có thể thu hồi nó thay vì chờ nó hết hạn.

Profile Key

Profile-Key cho biết liên kết dành cho User Profile nào. Bạn tìm thấy nó trong bảng điều khiển nhà phát triển của Ayrshare bằng cách chuyển sang profile đó.
Private Key không còn được dùng. Các liên kết không được ký, nên không có gì phải đọc từ tệp hay dán vào mã của bạn. Tham số cũ privateKey vẫn được chấp nhận và bị bỏ qua, nên các tích hợp hiện có tiếp tục hoạt động, và tệp private.key trong Integration Package của bạn có thể để không dùng.

Chuyển đổi Profile

Nếu một profile đã đăng nhập, việc mở liên kết của một profile khác sẽ không chuyển đổi profile — điều đó là cố ý, và nó giữ trải nghiệm nhanh cho người dùng đã ở sẵn đó. Để buộc chuyển đổi, xem Tự động đăng xuất phiên Profile. Tài khoản Instagram có thể được liên kết theo hai cách: trực tiếp với Instagram Login, hoặc thông qua Facebook Page đã kết nối. Luồng nào bắt đầu khi người dùng nhấp vào nút Instagram thường được kiểm soát bởi cài đặt Instagram Login toàn tài khoản. Tham số body instagramLinkMethod ghi đè cài đặt đó cho một liên kết duy nhất:
Instagram Link Method
Ghi đè này áp dụng trong suốt vòng đời của liên kết đó, bao gồm cả trong quá trình chuyển hướng ủy quyền Instagram/Facebook. Một vài điều cần biết:
  • Nó không thay đổi cài đặt toàn tài khoản của bạn hoặc ảnh hưởng đến bất kỳ liên kết nào khác.
  • Bỏ qua nó và cài đặt toàn tài khoản sẽ áp dụng, giống hệt như trước.
  • Một giá trị không hợp lệ trả về 400 liệt kê các giá trị hợp lệ (instagram, facebook).
  • Xem lại sự khác biệt về tính năng trước khi chọn — một số tính năng Instagram, như tìm kiếm hashtag và cộng tác, chỉ khả dụng với xác thực Facebook Page.

Connect Accounts Email

Ayrshare có thể thay bạn gửi email liên kết đến người dùng của bạn, để họ đến được trang liên kết của họ mà không cần vào ứng dụng của bạn. Hãy kết hợp nó với một expiresIn dài hơn — 5 phút mặc định hiếm khi tồn tại nổi trong hộp thư đến.

Connect Accounts JSON

Mọi trường bên trong email đều bắt buộc. Thiếu một trường sẽ làm lần gửi thất bại.
Example Contact Email Request
expiresIn là tham số cấp cao nhất, không phải một phần của đối tượng email. Nếu lồng bên trong email, nó bị bỏ qua, và người dùng của bạn nhận được một liên kết hết hạn sau 5 phút.
Phản hồi báo cáo kết quả trong emailSent:
Example Contact Email Response
Nếu không gửi được email, yêu cầu vẫn thành công và bạn vẫn nhận được liên kết. Phản hồi có emailSent: false cùng một đối tượng emailError, để bạn có thể gửi liên kết cho người dùng theo cách khác:
Example Failed Email Response
emailError xuất hiện bất cứ khi nào bạn yêu cầu gửi email nhưng email không được gửi: hoặc việc gửi thất bại, hoặc đối tượng email thiếu một trường bắt buộc, khi đó details sẽ nêu các trường bị thiếu. emailSent: false mà không có emailError nghĩa là không có email nào được yêu cầu. Thiếu to thì khác: toàn bộ yêu cầu sẽ bị từ chối với code: 188.

Ví dụ Email Connect Accounts

Đây là một ví dụ về email mở trang liên kết mạng xã hội: Connect Accounts email Email sẽ đến từ địa chỉ: Social Connect Hub <connect@socialconnecthub.com>

Ứng dụng Mobile

Hãy mở URL liên kết trong trình duyệt hệ thống, không bao giờ trong webview nhúng: Google từ chối đăng nhập trong đó với disallowed_useragent, và Meta chặn hoàn toàn. Người dùng của bạn sẽ thấy trang lỗi của chính mạng xã hội, và không có gì ở phía bạn khắc phục được điều đó.
  • iOS — ASWebAuthenticationSession, hoặc SFSafariViewController.
  • Android — Chrome Custom Tabs.
Vì ứng dụng gốc không có cửa sổ trình duyệt để nhận các sự kiện, hãy lấy kết quả từ Lấy một Link Session thay thế. Đặt origin là custom scheme của bạn (myapp://connected) để trang có đường quay lại ứng dụng của bạn.

Ví dụ mã Mobile

Thay thế linkingURL bằng url được trả về từ Tạo một Link Session.

Thử nghiệm

Khuyến nghị trước tiên hãy tạo một liên kết trong Postman. Integration Package của bạn — ở trang API Key của Primary Profile trên dashboard — bao gồm một cấu hình Postman mẫu. Hãy import nó, điền Profile Key của bạn vào trường body profileKey, và nhấp Send. Cấu hình mẫu vẫn điền trước privateKey và domain. privateKey bị bỏ qua, và bạn có thể xóa domain trừ khi tài khoản của bạn có nhiều hơn một domain liên kết. Bạn cũng có thể tạo mã từ Postman.

Bubble.io

Bubble linking URL

Legacy: generateJWT

Tạo URL liên kết (generateJWT) thực hiện cùng công việc và đã ngừng khuyến nghị (deprecated) — vẫn được hỗ trợ đầy đủ, không có ngày gỡ bỏ, và không thay đổi đối với các liên kết bạn đã phát đi. Trang riêng của nó ghi lại các tham số của nó, bao gồm ba tham số giờ đây được chấp nhận và bị bỏ qua.Cả hai endpoint chạy cùng một bộ kiểm tra, nên mọi thứ trên trang này áp dụng cho cả hai. Một khác biệt đáng biết khi bạn di chuyển: generateJWT dung thứ ba điều mà Tạo một Link Session từ chối — một mạng allowedSocial không nhận diện được, chỉ một nửa thông tin xác thực X, và redirect không phải chuỗi.