Chuyển đến nội dung chính

Giới thiệu

Quản lý người dùng đã đăng ký — lấy hồ sơ, cập nhật dữ liệu và xử lý trạng thái tài khoản.

Thông tin thêm về quản lý người dùng trong bảng điều khiển quản trị OneEntry: https://doc.oneentry.cloud/docs/category/users

🎯 Mô-đun này làm gì?​

Mô-đun Users quản lý người dùng đã xác thực: lấy hồ sơ, cập nhật dữ liệu biểu mẫu và đối tượng state tùy chỉnh, lưu trữ hoặc xóa tài khoản, quản lý giỏ hàng và danh sách yêu thích theo từng người dùng (hoặc khách), và đăng ký mã FCM cho thông báo đẩy.

Đăng ký và đăng nhập không nằm ở đây — chúng nằm trong mô-đun AuthProvider. Mô-đun Users làm việc với người dùng mà AuthProvider đã xác thực.

🚀 Khởi động nhanh​

Khởi tạo mô-đun từ defineOneEntry:


const { Users } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Lấy người dùng hiện tại và cập nhật đối tượng state tùy chỉnh của họ (giả định có phiên xác thực — xem AuthProvider):

// Fetch the authorized user's profile and state.
const user = await Users.getUser("en_US");

console.log(user.id, user.identifier);

// Update the user, preserving existing state.
await Users.updateUser({
  formIdentifier: user.formIdentifier,
  formData: user.formData,
  state: { ...user.state, orderCount: (user.state.orderCount || 0) + 1 },
});

✨ Khái niệm chính​

Người dùng là gì?​

Người dùng là một tài khoản đã đăng ký trong ứng dụng của bạn:

  • Định danh - giá trị đăng nhập (email, điện thoại hoặc tên người dùng)
  • Nhà cung cấp xác thực - phương thức xác thực được sử dụng (authProviderIdentifier)
  • Dữ liệu biểu mẫu - các trường hồ sơ được xác định bởi biểu mẫu đăng ký (formData)
  • Nhóm - mảng ID nhóm mà người dùng thuộc về
  • Đối tượng trạng thái - dữ liệu ứng dụng tùy chỉnh

Cấu trúc người dùng​

Mỗi người dùng có cấu trúc này:

{
  id: 8,                                    // User ID
  identifier: 'test@test.ru',               // User identifier (email/login)
  authProviderIdentifier: 'email',          // Auth provider type
  formIdentifier: 'reg',                    // Registration form identifier
  formData: [                               // User profile data
    { marker: 'name_reg', type: 'string', value: 'Ivan' },
    { marker: 'phone_reg', type: 'string', value: '+19258382556' },
  ],
  groups: [1],                              // User groups for permissions
  state: {},                                // Custom application data
  moduleFormConfigs: [],                    // Additional form configurations
}

Đối tượng trạng thái​

Bạn có thể lưu trữ bất kỳ dữ liệu cụ thể nào của ứng dụng trong đối tượng state theo từng người dùng. Khi bạn cập nhật người dùng, hãy thêm dữ liệu bạn cần vào state; các cuộc gọi getUser() tiếp theo sẽ trả lại nó.

Trường hợp sử dụngVí dụ trạng tháiMô tả
Thương mại điện tử{ orderCount: 5, totalSpent: 499.99 }Theo dõi lịch sử mua hàng
Nội dung{ articlesRead: 25, bookmarks: [1,2,3] }Theo dõi tiêu thụ nội dung
Trò chơi{ level: 15, score: 9500, achievements: [...] }Theo dõi tiến trình trò chơi
SaaS{ plan: 'premium', usage: 75 }Theo dõi dữ liệu đăng ký

Luôn bảo tồn trạng thái hiện có khi cập nhật — hãy trải nó ra để không làm mất các trường khác:

// ❌ Bad - overwrites the entire state
const state = { orderCount: 1 };

// ✅ Good - preserve existing state
const state = {
  ...user.state,
  orderCount: (user.state.orderCount || 0) + 1,
};

📋 Những điều bạn cần biết​

Cần xác thực​

Mỗi phương thức người dùng yêu cầu một phiên đã được xác thực — hãy xác thực người dùng trước thông qua mô-đun AuthProvider. Các phương thức giỏ hàng và danh sách yêu thích cũng hoạt động cho khách (xem phần Giỏ hàng & Danh sách yêu thích bên dưới).

Dữ liệu biểu mẫu người dùng​

Dữ liệu hồ sơ người dùng theo các biểu mẫu được cấu hình trong bảng điều khiển quản trị OneEntry:

  • Mỗi người dùng có một formIdentifier tham chiếu đến biểu mẫu đăng ký đã sử dụng.
  • Các trường hồ sơ nằm trong mảng formData dưới dạng các mục marker / type / value.
  • Các loại trường được hỗ trợ bao gồm: chuỗi, số nguyên, số thực, ngày, ngày giờ, thời gian, văn bản, văn bản có tiêu đề, hình ảnh, nhóm hình ảnh, tệp, nút radio, danh sách, thực thể, khoảng thời gian.

Hướng dẫn đối tượng trạng thái​

  • Chỉ lưu trữ dữ liệu cụ thể của ứng dụng; không đặt mật khẩu, mã thông báo hoặc dữ liệu thẻ vào state.
  • Giữ cho nó được tổ chức với các đối tượng lồng nhau và đặt tên nhất quán.
  • Cập nhật bằng cách trải dữ liệu state hiện có (xem ở trên) — không bao giờ ghi đè một cách mù quáng.

Dữ liệu thông báo​

Khi cập nhật một người dùng, bạn có thể truyền một đối tượng notificationData với các kênh giao hàng:

  • email - địa chỉ email cho thông báo
  • phonePush - mảng số điện thoại cho thông báo đẩy
  • phoneSMS - số điện thoại cho thông báo SMS

Phân trang​

Đối với danh sách giỏ hàng/danh sách yêu thích và các bộ sưu tập khác, hãy phân trang qua các kết quả thay vì tải tất cả cùng một lúc.

📊 Bảng tham khảo nhanh​

Phương thứcMô tảTrường hợp sử dụng
getUser() 🔐Lấy dữ liệu người dùng đã xác thựcLấy hồ sơ người dùng hiện tại
updateUser() 🔐Cập nhật thông tin người dùngCập nhật hồ sơ, thay đổi trạng thái
archiveUser() 🔐Lưu trữ tài khoản người dùngXóa mềm tài khoản người dùng
deleteUser() 🔐Xóa vĩnh viễn người dùngXóa cứng tài khoản người dùng
addFCMToken() 🔐Thêm mã FCM cho thông báo đẩyKích hoạt thông báo đẩy
deleteFCMToken() 🔐Xóa mã FCMVô hiệu hóa thông báo đẩy
getCart()Lấy giỏ hàng của người dùng hoặc kháchĐọc giỏ hàng hiện tại
setCart()Thay thế toàn bộ giỏ hàngĐồng bộ giỏ hàng phía client
addCartItem()Thêm một mục vào giỏ hàngHành động "Thêm vào giỏ hàng"
removeCartItem()Xóa một mục khỏi giỏ hàngHành động "Xóa khỏi giỏ hàng"
getWishlist()Lấy danh sách yêu thích của người dùng hoặc kháchĐọc danh sách yêu thích hiện tại
setWishlist()Thay thế toàn bộ danh sách yêu thíchĐồng bộ danh sách yêu thích phía client
addWishlistItem()Thêm một mục vào danh sách yêu thíchHành động "Thêm vào danh sách yêu thích"
removeWishlistItem()Xóa một mục khỏi danh sách yêu thíchHành động "Xóa khỏi danh sách yêu thích"

🔐 đánh dấu các phương thức yêu cầu một phiên người dùng đã xác thực (AuthProvider). Các phương thức giỏ hàng và danh sách yêu thích cũng hoạt động cho khách.

🛒 Giỏ hàng & Danh sách yêu thích​

Các phương thức giỏ hàng và danh sách yêu thích hoạt động cho cả người dùng đã xác thực và khách. Đối với một khách, SDK gửi một tiêu đề x-guest-id để giỏ hàng/danh sách yêu thích được liên kết với khách truy cập ẩn danh đúng - xem Chế độ khách. Khi một khách đăng nhập, các phương thức tương tự hoạt động trên dữ liệu của người dùng đã xác thực.

Các phương thức này cũng cung cấp cho các khối cá nhân hóa (chẳng hạn như bổ sung giỏ hàng, giỏ hàng tương tự và danh sách yêu thích tương tự) và có thể được kết hợp với theo dõi hoạt động người dùng.

❓ Câu hỏi thường gặp (FAQ)​

Đối tượng trạng thái người dùng là gì và tôi nên sử dụng nó như thế nào?​

Đối tượng state là một kho lưu trữ JSON linh hoạt cho dữ liệu người dùng cụ thể của ứng dụng. Sử dụng nó để theo dõi các chỉ số tùy chỉnh như số lượng đơn hàng, sở thích hoặc tiến trình. Luôn trải trạng thái hiện có khi cập nhật để tránh ghi đè dữ liệu khác.

Làm thế nào để tôi cập nhật thông tin hồ sơ người dùng?​

Sử dụng updateUser() để sửa đổi các trường dữ liệu biểu mẫu, cài đặt thông báo và đối tượng state. Xác thực người dùng trước thông qua mô-đun AuthProvider.

Sự khác biệt giữa archiveUser() và deleteUser() là gì?​

archiveUser() là một xóa mềm đánh dấu người dùng để xóa nhưng vẫn bảo tồn dữ liệu. deleteUser() xóa vĩnh viễn tài khoản người dùng. Sử dụng lưu trữ trừ khi bạn cần xóa hoàn toàn dữ liệu.

Làm thế nào để tôi xử lý thông báo đẩy cho người dùng?​

Sử dụng addFCMToken() để đăng ký một mã thông báo Firebase Cloud Messaging cho người dùng, cho phép thông báo đẩy đến thiết bị của họ. Sử dụng deleteFCMToken() khi họ đăng xuất hoặc vô hiệu hóa thông báo.

Làm thế nào để tôi lấy dữ liệu người dùng sau khi đăng ký?​

Sau khi đăng ký thành công và xác thực qua AuthProvider, gọi getUser() để lấy hồ sơ người dùng đã xác thực và đối tượng state tùy chỉnh.

🎓 Thực hành tốt nhất​

  • Xác thực trước - mỗi phương thức người dùng yêu cầu một phiên đã xác thực (xem mô-đun AuthProvider).
  • Bảo tồn trạng thái hiện có - trải dữ liệu hiện có khi cập nhật state.
  • Không lưu trữ dữ liệu nhạy cảm trong state - giữ mật khẩu, mã thông báo và dữ liệu thẻ ra khỏi state.
  • Lưu trữ dữ liệu người dùng - giảm số lần gọi API cho dữ liệu thường xuyên được truy cập.

🔗 Tài liệu liên quan​