Custom tags

Custom tag là một biến tùy chỉnh với giá trị đến từ ứng dụng của bạn. Sau khi bạn chọn Value comes from outside the app trong cài đặt của biến, ứng dụng của bạn có thể đặt giá trị đó thông qua SDK Adapty. Ví dụ: một phần tử văn bản chứa “Coins:” và một custom tag. Nếu ứng dụng của bạn truyền “120” cho tag đó, người dùng sẽ thấy “Coins: 120”.

Sử dụng custom tag để hiển thị:

• Người dùng là ai: Tên người dùng trong lời chào, chẳng hạn như “Welcome back, DragonSlayer42!”
• Người dùng có gì: Số ngày streak, hoặc cấp độ của người chơi.
• Những gì ứng dụng tính toán: Mức giảm giá cho gói lớn hơn, hoặc BMI dựa trên câu trả lời của người dùng trong một flow trước đó.

Giá trị và fallback

App của bạn nhận diện mỗi giá trị qua tên thẻ tùy chỉnh của nó. Giá trị luôn là một chuỗi ký tự. Adapty không định dạng hay dịch chuỗi đó, vì vậy app của bạn phải chuyển đổi giá trị thành dạng dễ đọc trước khi hiển thị trong flow. Ví dụ: truyền vào “1,250” thay vì “1250.0”.

Người dùng sẽ thấy Giá trị ban đầu của thẻ tùy chỉnh như một giá trị dự phòng trong các trường hợp sau:

• Ứng dụng của bạn không truyền giá trị nào cho thẻ đó.
• Người dùng chưa cập nhật ứng dụng lên phiên bản có truyền giá trị.
• Tên trong code của ứng dụng không khớp với tên đầy đủ của thẻ, bao gồm cả chữ hoa/thường.
• Một thẻ tùy chỉnh khác trong cùng phần tử văn bản không có giá trị. Khi đó, mọi thẻ tùy chỉnh trong phần tử văn bản đó đều hiển thị giá trị ban đầu của chúng.

Để không hiển thị gì thay cho thẻ, hãy truyền một chuỗi rỗng. Adapty coi chuỗi rỗng là một giá trị hợp lệ, vì vậy giá trị dự phòng sẽ không xuất hiện.

1. Tạo thẻ tùy chỉnh

1. Mở bảng Variables trong flow builder.

2. Thêm biến mới — nhấp vào .

3. Cấu hình Name cho biến. Mã nguồn trong app phải tham chiếu chính xác tên này, bao gồm cả chữ hoa/thường.

   • Characters: Dùng chữ cái Latin (A–Z và a–z), chữ số, _, và -. Để đưa tag vào một nhóm, bắt đầu tên bằng tên nhóm và dấu chấm, ví dụ user.streak.
   • Reserved names: Dù viết hoa hay thường, không dùng tên đã được đặt trước như PRICE, TITLE, VALUE, hoặc tên bắt đầu bằng TIMER_.
   • Uniqueness: Dùng tên duy nhất trong phạm vi flow.

4. (Tùy chọn) Để phân biệt các biến với nhau, điền vào trường Description. Khi di chuột qua tên biến trong builder, bạn sẽ thấy mô tả này.

5. Trong trường Initial value, nhập giá trị dự phòng mà người dùng thấy khi app không truyền giá trị nào:

   • Một từ phù hợp với mọi người dùng: Với tag username trong lời chào, nhập friend. Người dùng chưa đăng nhập sẽ thấy “Welcome back, friend!”. Lưu ý rằng giá trị ban đầu không thể được bản địa hóa.
   • Dấu gạch ngang cho số dư hoặc số lượng: Để tránh hiển thị số dư sai cho người dùng chưa đăng nhập, nhập dấu gạch ngang (—).

6. (Chỉ dành cho biến kiểu String) Chọn hộp kiểm Value comes from outside the app. Thao tác này không thể hoàn tác và sẽ khóa Value Type.

7. Nhấn Create variable.

Biến chỉ có hiệu lực trong phạm vi flow cụ thể đó. Để sử dụng custom tag trong flow khác, hãy tạo một biến mới ở đó với cùng tên.

Thay thế biến bằng custom tag

Bạn chỉ có thể chọn checkbox Value comes from outside the app khi tạo biến. Để hiển thị giá trị từ ứng dụng thay cho một biến tùy chỉnh thông thường, chẳng hạn như biến từ một paywall được chuyển đổi, hãy thay thế biến đó bằng một custom tag:

1. Xóa biến và tất cả các tham chiếu đến nó trong flow.
2. Tạo một custom tag với cùng tên.
3. Chèn custom tag vào từng phần tử văn bản đã sử dụng biến đó.

2. Thêm thẻ tùy chỉnh vào một phần tử văn bản

Chọn phần tử văn bản. Trong phần Content, nhấn Add variable, rồi chọn thẻ trong tab Custom.

Bạn có thể chèn thẻ tùy chỉnh vào mọi nhánh của văn bản có điều kiện, nhưng không thể chọn chúng trong điều kiện if của văn bản đó.

3. Truyền giá trị từ ứng dụng của bạn

Mã nguồn trong ứng dụng của bạn phải sử dụng đúng tên của từng custom tag, bao gồm cả tên nhóm. Ví dụ: nếu nhóm user chứa tag streak, tên đầy đủ của tag đó là user.streak.

Mã thiết lập phụ thuộc vào nền tảng bạn đang dùng:

• iOS
• Android
• React Native
• Flutter
• Unity
• Kotlin Multiplatform
• Capacitor

Để kiểm tra các custom tag của bạn, hãy mở flow trong ứng dụng sau khi thêm code thiết lập giá trị cho chúng. Canvas của builder và xem trước trên thiết bị chỉ hiển thị giá trị ban đầu: ứng dụng Adapty trên thiết bị di động không thiết lập giá trị cho custom tag.

Hạn chế

• Chỉ dùng cho thành phần văn bản: Bạn chỉ có thể chèn custom tag vào các thành phần văn bản. Không thể chèn vào:
  • Hành động Set variable
  • Hành động Show alert
  • Hành động Open URL
  • Placeholder của input
• Không dùng điều kiện với custom tag: Bạn không thể chọn custom tag trong điều kiện hoặc trong conditional visibility. Để quyết định câu chữ, thành phần và màn hình người dùng thấy dựa trên giá trị từ app:
  • Câu chữ: Xây dựng câu trong code của app, rồi truyền vào làm giá trị của tag. Ví dụ, với tag coins_message, truyền “You have 120 coins” cho người chơi có coins, và “Get your first coins” cho những người còn lại.
  • Thành phần và màn hình: Đặt giá trị làm custom attribute. Sau đó hiển thị một flow riêng cho đối tượng được tạo từ attribute đó.
• Không có phương thức SDK để cập nhật giá trị trong flow đang mở: Để hiển thị kết quả dựa trên những gì người dùng nhập vào trong flow, hãy truyền kết quả đó sang flow tiếp theo, như trong ví dụ BMI.