Patreon Authenticator for Unity

Bắt đầu

Patreon Authenticator for Unity là plugin mạnh mẽ giúp tích hợp game Unity của bạn với hệ thống xác thực của Patreon một cách liền mạch. Với nó, bạn có thể:

• Bảo mật nâng cao: mã hóa AES-256, làm rối mã và lưu trữ an toàn
• Máy chủ HTTP tích hợp: HTTP listener nhúng cho callback OAuth
• Hỗ trợ middleware: middleware tùy chỉnh cho callback OAuth trên mọi nền tảng
• Đa nền tảng: chạy trên WebGL, Android, iOS, Windows, Mac và Linux
• Quản lý token an toàn: mã hóa theo thiết bị với dẫn xuất khóa PBKDF2
• Thao tác an toàn luồng: xử lý request HTTP đúng cách
• Giao diện callback đẹp: trang HTML thành công và lỗi tùy chỉnh được
• Xác thực state: chống CSRF bằng kiểm tra tham số state
• Làm mới token: tự động làm mới access token
• Lấy hồ sơ người dùng: dữ liệu người dùng và thông tin thành viên
• Kiểm thử bảo mật: công cụ tích hợp để xác minh và kiểm thử bảo mật
• Hỗ trợ GIF: avatar Patreon động với hỗ trợ hoạt ảnh GIF

Yêu cầu

Trước khi bắt đầu, hãy chắc chắn bạn có:

• Unity 2021.3 LTS trở lên
• .NET Standard 2.1 trở lên
• Tài khoản nhà sáng tạo Patreon
• Kiến thức cơ bản về Unity và C#
• Kết nối internet cho các request API Patreon

Cài đặt

1. Cài gói Newtonsoft.Json (bắt buộc)

QUAN TRỌNG: bước này bắt buộc trước khi dùng plugin!

1. Mở Package Manager trong Unity (Window → Package Manager)
2. Nhấn nút "+"
3. Chọn "Install package by name…"
4. Enter com.unity.nuget.newtonsoft-json
5. Nhấn "Add" để cài gói

Thiếu gói này, các script sẽ không biên dịch được!

2. Sao chép tệp plugin

1. Sao chép thư mục Assets/Plugins/PatreonAuthenticatorForUnity/ vào dự án Unity của bạn
2. Sao chép tệp Assets/StreamingAssets/patreon-callback.html vào thư mục StreamingAssets

3. Thiết lập scene

1. Tạo asset PatreonConfig:
   • Vào thư mục Resources (tạo nếu chưa có)
   • Nhấp chuột phải trong cửa sổ Project
   • Vào Create → Patreon Authenticator for Unity → Create New Config
   • Asset sẽ được tạo trong thư mục Assets/Resources/ (PatreonConfig)
   • Đặt các cài đặt cơ bản (xem mục Cấu hình bên dưới)
   • Client ID và Client Secret sẽ được đặt sau bằng script PatreonReEncryptCredentials
2. Tạo GameObject PatreonManager:
   • Nhấp chuột phải trong cửa sổ Hierarchy
   • Chọn Create Empty
   • Đổi tên GameObject thành PatreonManager
3. Thêm các script cần thiết vào PatreonManager:
   • Chọn GameObject PatreonManager
   • Add Component → script PatreonManager
   • QUAN TRỌNG: gán asset PatreonConfig vào trường "Patreon Config"
   • Add Component → script PatreonCallbackManager (chạy trên mọi nền tảng, cần các component bên dưới)
   • Add Component → script PatreonEmbeddedServer (chỉ nền tảng desktop)
   • Add Component → script PatreonDeepLinkHandler (chỉ nền tảng di động)
   • Add Component → script PatreonWebGLHandler (chỉ nền tảng WebGL)

   Tất cả script đều tương thích và có thể dùng cùng nhau.

4. Thiết lập theo nền tảng:

   📱 Nền tảng di động (Android/iOS):

   • PatreonDeepLinkHandler sẽ được dùng tự động
   • Thiết lập Android: thêm vào AndroidManifest.xml của bạn:

     <activity android:name="com.unity3d.player.UnityPlayerActivity">
       <intent-filter>
         <action android:name="android.intent.action.VIEW" />
         <category android:name="android.intent.category.DEFAULT" />
         <category android:name="android.intent.category.BROWSABLE" />
         <data android:scheme="PatreonAuthenticatorForUnity.oauth" />
       </intent-filter>
     </activity>
     

   • Thiết lập iOS: thêm vào Info.plist của bạn:

     <key>CFBundleURLTypes</key>
     <array>
       <dict>
         <key>CFBundleURLName</key>
         <string>Patreon OAuth</string>
         <key>CFBundleURLSchemes</key>
         <array>
           <string>PatreonAuthenticatorForUnity.oauth</string>
         </array>
       </dict>
     </array>
     

   🌐 Nền tảng WebGL:

   • PatreonWebGLHandler sẽ được dùng tự động
   • Dùng middleware cho callback OAuth (không cần thiết lập thêm)

   🖥️ Nền tảng desktop (Windows/Mac/Linux):

   • PatreonEmbeddedServer sẽ được dùng tự động
   • Tạo máy chủ HTTP cục bộ tại localhost:3000
5. Về middleware:
   • Mọi nền tảng đều dùng middleware cho callback OAuth
   • Middleware xử lý luồng OAuth và chuyển hướng về ứng dụng của bạn
   • Lược đồ URI tùy chỉnh: đặt trong PatreonConfig (mặc định: PatreonAuthenticatorForUnity.oauth)
   • Lựa chọn middleware miễn phí: bạn có thể tạo middleware riêng trên GitHub Pages
   • Sao chép mã middleware từ Assets/StreamingAssets/patreon-callback.html
   • Host trên GitHub Pages để có middleware miễn phí
   • Cập nhật redirect URI trong PatreonConfig trỏ đến middleware của bạn
   • Lược đồ URI tùy chỉnh: cấu hình middleware theo lược đồ URI của bạn từ PatreonConfig
6. Kiểm tra thiết lập của bạn:
   • GameObject PatreonManager phải có đủ các script cần thiết
   • PatreonConfig phải được gán trong component PatreonManager
   • Không được có lỗi biên dịch trong Console

Tính năng bảo mật

Hệ thống mã hóa nâng cao

Plugin có hệ thống bảo mật đầy đủ để bảo vệ thông tin đăng nhập Patreon của bạn:

Mã hóa AES-256

• Client Secret được mã hóa AES-256 với khóa riêng theo thiết bị
• Dẫn xuất khóa PBKDF2 với 10,000 vòng lặp để bảo mật tối đa
• Mã hóa theo thiết bị — khóa riêng cho từng thiết bị/ứng dụng
• Tự động tạo IV cho mỗi lần mã hóa

Làm rối XOR

• Client ID được làm rối bằng mã hóa XOR
• Mã hóa Base64 để lưu trữ an toàn
• Bảo vệ nhẹ phù hợp cho định danh công khai

Lưu trữ an toàn

• Lưu trữ PlayerPrefs mã hóa cho dữ liệu nhạy cảm
• Tự động xóa dữ liệu nhạy cảm khỏi bộ nhớ
• Phương thức xóa an toàn cho dữ liệu đã lưu

Xác minh bảo mật

• Kiểm thử bảo mật tích hợp với component PatreonSecurityTest
• Tự động xác minh thao tác mã hóa/giải mã
• Kiểm thử hiệu năng cho các thao tác bảo mật
• Xác minh an toàn bộ nhớ

Mức bảo mật

Thực hành bảo mật tốt nhất

1. Luôn bật mã hóa cho Client Secret trong production
2. Dùng làm rối cho Client ID khi có thể
3. Không bao giờ commit PatreonConfig.asset vào hệ thống quản lý phiên bản
4. Kiểm thử hệ thống bảo mật trước khi build production
5. Dùng lưu trữ an toàn cho mọi dữ liệu nhạy cảm
6. Xóa dữ liệu nhạy cảm khỏi bộ nhớ khi không còn cần

QUAN TRỌNG: thiết lập thông tin xác thực an toàn

ĐIỀU NÀY CỰC KỲ QUAN TRỌNG VỀ BẢO MẬT!

Thông tin xác thực Patreon của bạn (Client ID và Client Secret) cực kỳ nhạy cảm và phải được mã hóa trước khi dùng. KHÔNG BAO GIỜ lưu chúng dưới dạng văn bản thô!

Vì sao điều này quan trọng

• Văn bản thô = rủi ro bảo mật: nếu thông tin xác thực lưu dạng văn bản thô, bất kỳ ai truy cập được bản build đều có thể đánh cắp
• Ảnh hưởng tài chính: thông tin bị đánh cắp có thể dùng để truy cập tài khoản Patreon của bạn và gây thiệt hại tài chính
• Ảnh hưởng nghề nghiệp: sự cố bảo mật có thể làm tổn hại uy tín và lòng tin của người dùng
• Hệ quả pháp lý: biện pháp bảo mật không đầy đủ có thể dẫn đến vấn đề pháp lý

Cách thiết lập thông tin xác thực an toàn

Làm theo các bước sau để mã hóa thông tin xác thực Patreon:

Bước 1: Tạo GameObject mã hóa lại

1. Tạo một GameObject rỗng mới trong scene
2. Đổi tên thành kiểu như "PatreonEncryptCredentials" (bạn sẽ xóa nó sau)
3. Thêm script PatreonEncryptCredentials vào GameObject

Bước 2: Nhập thông tin xác thực thật

1. Chọn GameObject trong Hierarchy
2. Trong Inspector, bạn sẽ thấy script mã hóa lại kèm hướng dẫn rõ ràng
3. Điền thông tin xác thực thật vào các ô tương ứng:
   • Real Client Id: Client ID Patreon của bạn
   • Real Client Secret: Client Secret Patreon của bạn

Bước 3: Gán PatreonConfig (không bắt buộc nhưng nên làm)

1. Kéo asset PatreonConfig vào ô PatreonConfig Asset
2. Nếu gán PatreonConfig: giá trị được đặt tự động sau khi mã hóa
3. Nếu không gán PatreonConfig: bạn cần tự sao chép các giá trị đã mã hóa

Bước 4: Mã hóa lại thông tin xác thực

1. Nhấp chuột phải vào script trong Inspector
2. Chọn “Re-Encrypt All Credentials” trong menu ngữ cảnh
3. Chờ quá trình hoàn tất - bạn sẽ thấy thông báo thành công trong Console

Bước 5: Kiểm tra và dọn dẹp

1. Xem Console để tìm thông báo thành công
2. Nếu đã gán PatreonConfig: giá trị được đặt tự động
3. Nếu CHƯA gán PatreonConfig: tự sao chép giá trị đã mã hóa vào PatreonConfig
4. Xóa GameObject - scene không cần nó nữa

Cấu hình

Thiết lập Patreon

Trước khi cấu hình plugin trong Unity, bạn cần thiết lập ứng dụng Patreon:

1. Trở thành nhà sáng tạo trên Patreon:
   • Bạn phải là nhà sáng tạo trên Patreon để đăng ký OAuth client
   • Vào Patreon Developer Console
2. Tạo OAuth client:
   • Nhấn “Create Client” hoặc “Register New Client”
   • Điền thông tin ứng dụng
   • QUAN TRỌNG: đặt redirect URI là: http://localhost:3000/patreon-callback
   • Giá trị này phải khớp chính xác với redirect URI trong PatreonConfig
3. Lấy thông tin xác thực:
   • Client ID: sao chép từ cài đặt OAuth client
   • Client Secret: sao chép từ cài đặt OAuth client (giữ bí mật!)
   • Creator ID: tên người dùng Patreon của bạn (vd. nếu Patreon là patreon.com/DryreL thì Creator ID là DryreL)

CẢNH BÁO BẢO MẬT:

• KHÔNG BAO GIỜ chia sẻ Client ID và Client Secret với bất kỳ ai
• KHÔNG BAO GIỜ commit các giá trị này vào hệ thống quản lý phiên bản
• KHÔNG BAO GIỜ đăng chúng lên diễn đàn công khai hay kênh Discord
• Các thông tin này cho toàn quyền truy cập tài khoản Patreon của bạn

Cài đặt Unity

Sau khi tạo asset PatreonConfig (xem Thiết lập scene ở trên), cấu hình API Patreon:

• Redirect URI: http://localhost:3000/patreon-callback (phải khớp với cài đặt trong console Patreon)
• Creator ID: tên người dùng Patreon của bạn (vd. DryreL cho patreon.com/DryreL)
• Authentication Timeout: thời gian chờ người dùng xác thực (mặc định: 120 giây)

QUAN TRỌNG: Redirect URI trong PatreonConfig phải khớp chính xác với cài đặt trong Patreon Developer Console!

QUAN TRỌNG: không bao giờ commit PatreonConfig vào hệ thống quản lý phiên bản!

• Thêm Assets/Resources/PatreonConfig.asset vào tệp .gitignore
• Tệp này chứa thông tin xác thực API nhạy cảm

Client ID và Client Secret sẽ được đặt tự động khi bạn dùng script PatreonEncryptCredentials!

🌐 Hướng dẫn thiết lập middleware

Dùng lược đồ URI động

Plugin này giờ dùng hệ thống middleware cho phép mọi nền tảng dùng chung một redirect URI.

1. Tạo URL OAuth:

https://yourdomain.com/api/oauth/redirect?scheme=YOUR_APP_SCHEME

Ví dụ:

• https://yourdomain.com/api/oauth/redirect?scheme=mygame.oauth
• https://yourdomain.com/api/oauth/redirect?scheme=awesomeapp.auth
• https://yourdomain.com/api/oauth/redirect?scheme=unitygame.patreon

2. Cài đặt ứng dụng Patreon:

• Redirect URI: https://yourdomain.com/api/oauth/redirect?scheme=YOUR_APP_SCHEME
• Client ID: như trước
• Client Secret: như trước

3. Thiết lập nền tảng:

Android (AndroidManifest.xml):

<activity android:name="com.unity3d.player.UnityPlayerActivity">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="YOUR_APP_SCHEME" />
    </intent-filter>
</activity>

iOS (Info.plist):

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>Patreon OAuth</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>YOUR_APP_SCHEME</string>
        </array>
    </dict>
</array>

4. Thiết lập PatreonConfig:

Cấu hình lược đồ URI tùy chỉnh trong PatreonConfig:

• Custom URI Scheme: đặt theo lược đồ bạn muốn (vd. mygame.oauth)
• Redirect URI: cập nhật cho khớp URL middleware
• Mọi thay đổi: thực hiện qua giao diện PatreonConfig

5. URL thử nghiệm:

https://yourdomain.com/api/oauth/redirect?scheme=YOUR_APP_SCHEME&code=test123&state=test456

✅ Lợi ích:

• Một middleware cho mọi game
• Lược đồ động khác nhau cho mỗi game
• Thiết lập dễ, chỉ cần đổi lược đồ
• Tự động nhận diện nền tảng

🔧 Cách dùng:

1. Chọn lược đồ: mygame.oauth
2. Cài đặt ứng dụng Patreon: https://yourdomain.com/api/oauth/redirect?scheme=mygame.oauth
3. Sao chép tệp nền tảng và đổi lược đồ
4. Đặt customUriScheme trong Unity
5. Thử ngay! 🎯

👑 Thiết lập Creator API (không bắt buộc)

Cho các tính năng nâng cao như dữ liệu chiến dịch, danh sách thành viên và thông tin tier:

Bước 1: Lấy Creator's Access Token

1. Vào Patreon Developer Console
2. Tạo “Creator’s Access Token” (không phải OAuth Client)
3. Chọn scope: campaigns, campaigns.members, campaigns.tiers
4. Sao chép Access Token và Refresh Token

Bước 2: Bật Creator API

1. Trong script PatreonEncryptCredentials:
   • ✅ Đánh dấu “Enable Creator API”
   • Nhập Creator Access Token
   • Nhập Creator Refresh Token
2. Nhấn “Encrypt All Credentials”
3. Giá trị sẽ tự động được đặt vào PatreonConfig

Cách khác: cấu hình thủ công

Bạn cũng có thể đặt token Creator API trực tiếp trong PatreonConfig:

• Creator Access Token: đặt trong PatreonConfig để truy cập dữ liệu chiến dịch/thành viên
• Creator Refresh Token: đặt trong PatreonConfig để gia hạn token
• Enable Creator API: bật trong PatreonConfig để dùng tính năng nâng cao

Lưu ý: hãy chắc chắn đã mã hóa xong!

Bước 3: Dùng Creator API

// Get campaign information
StartCoroutine(PatreonManager.Instance.GetCampaignInfo());

// Get all campaign members/patrons
StartCoroutine(PatreonManager.Instance.GetCampaignMembers());

// Get campaign tiers/rewards
StartCoroutine(PatreonManager.Instance.GetCampaignTiers());

Bước 4: Hiển thị trên giao diện

Dùng PatreonUserInfoDisplay với các trường mới:

• Tên chiến dịch, Tóm tắt chiến dịch, Số patron
• Mức tier, Mô tả tier, Giới hạn tier
• Thành viên từ, Trạng thái ủng hộ, Lần thu tiếp theo

Tham khảo: Patreon API Guide

Xác thực

Quy trình đăng nhập

Quy trình xác thực tuân theo chuẩn OAuth 2.0:

1. Khởi tạo authenticator
2. Bắt đầu đăng nhập
3. Xử lý callback
4. Xác thực token

Đây là một ví dụ cơ bản:

using DryreL.Patreon;

public class PatreonManager : MonoBehaviour
{
    private PatreonAuthenticator authenticator;
    
    void Start()
    {
        authenticator = new PatreonAuthenticator();
        authenticator.OnLoginSuccess += OnLoginSuccess;
        authenticator.OnLoginFailed += OnLoginFailed;
    }
    
    public void Login()
    {
        authenticator.StartLogin();
    }
    
    private void OnLoginSuccess(PatreonUser user)
    {
        Debug.Log($"Welcome, {user.FullName}!");
        // Handle successful login
    }
    
    private void OnLoginFailed(string error)
    {
        Debug.LogError($"Login failed: {error}");
        // Handle login failure
    }
}

Quản lý token

Plugin tự động làm mới và lưu trữ token:

// Check if user is authenticated
if (authenticator.IsAuthenticated)
{
    // Get current user
    PatreonUser user = authenticator.CurrentUser;
    
    // Check subscription status
    bool isSubscriber = user.IsSubscriber;
    string tier = user.SubscriptionTier;
}

Tham chiếu API

Lớp

PatreonManager

Lớp singleton chính xử lý xác thực Patreon.

Thuộc tính:

• bool IsUserAuthenticated() - Trả về true nếu người dùng đã đăng nhập
• PatreonUser GetCurrentUser() - Lấy người dùng đã xác thực hiện tại
• string GetValidAccessToken() - Lấy access token hợp lệ (làm mới nếu cần)

Phương thức:

• void StartPatreonAuth() - Bắt đầu luồng OAuth Patreon
• void Logout() - Đăng xuất người dùng hiện tại và xóa token
• void SetAccessToken(string token) - Đặt access token
• void ExchangeCodeForToken(string code, string state) - Đổi mã ủy quyền lấy access token

PatreonUser

Đại diện cho một người dùng Patreon cùng thông tin đăng ký.

Thuộc tính:

• string Id - ID Patreon của người dùng
• string FullName - Họ tên đầy đủ của người dùng
• string Email - Địa chỉ email của người dùng
• string FirstName - Tên của người dùng
• string LastName - Họ của người dùng
• string Vanity - URL tùy chỉnh của người dùng
• string ImageUrl - URL ảnh đại diện của người dùng
• bool IsPatron - Người dùng có phải patron không
• float PledgeAmount - Số tiền ủng hộ tính bằng đô la
• bool HasPledge - Người dùng có khoản ủng hộ đang hoạt động không
• string DisplayName - Tên hiển thị của người dùng
• string PatronStatus - Trạng thái patron của người dùng
• string TierTitle - Tên tier đăng ký của người dùng
• int CentsPledged - Số tiền ủng hộ tính bằng cent

Phương thức:

• void LoadProfileAvatar(Action<Sprite> onComplete) - Tải avatar hồ sơ người dùng dưới dạng Sprite

Phương thức

StartLogin()

Bắt đầu luồng OAuth Patreon.

public void StartLogin()

Trả về: void

Ví dụ:

authenticator.StartLogin();

Logout()

Đăng xuất người dùng hiện tại và xóa token đã lưu.

public void Logout()

Trả về: void

Ví dụ:

authenticator.Logout();

Sự kiện

OnLoginSuccess

Kích hoạt khi người dùng đăng nhập thành công.

public event Action<PatreonUser> OnLoginSuccess;

Tham số:

• PatreonUser user - Người dùng đã xác thực

OnLoginFailed

Kích hoạt khi đăng nhập thất bại.

public event Action<string> OnLoginFailed;

Tham số:

• string error - Thông báo lỗi mô tả nguyên nhân

Ví dụ

Xác thực cơ bản

using UnityEngine;

public class SimplePatreonExample : MonoBehaviour
{
    void Start()
    {
        // Subscribe to events
        PatreonManager.OnUserAuthenticated += HandleLoginSuccess;
        PatreonManager.OnAuthenticationFailed += HandleLoginFailed;
    }
    
    public void LoginButtonClicked()
    {
        PatreonManager.Instance.StartPatreonAuth();
    }
    
    private void HandleLoginSuccess(PatreonUser user)
    {
        Debug.Log($"Welcome {user.FullName}!");
        
        if (user.IsPatron)
        {
            Debug.Log($"You are a patron with tier: {user.TierTitle}");
            Debug.Log($"Pledge amount: ${user.PledgeAmount:F2}");
            // Unlock premium content
        }
        else
        {
            Debug.Log("You are not a patron");
            // Show subscription prompt
        }
    }
    
    private void HandleLoginFailed(string error)
    {
        Debug.LogError($"Login failed: {error}");
        // Show error message to user
    }
}

Quản lý nội dung premium

public class PremiumContentManager : MonoBehaviour
{
    [SerializeField] private PatreonAuthenticator authenticator;
    [SerializeField] private GameObject premiumContent;
    
    void Start()
    {
        CheckSubscriptionStatus();
    }
    
    private void CheckSubscriptionStatus()
    {
        if (authenticator.IsAuthenticated)
        {
            PatreonUser user = authenticator.CurrentUser;
            
            if (user.IsSubscriber)
            {
                EnablePremiumContent(user.SubscriptionTier);
            }
            else
            {
                DisablePremiumContent();
            }
        }
        else
        {
            DisablePremiumContent();
        }
    }
    
    private void EnablePremiumContent(string tier)
    {
        premiumContent.SetActive(true);
        
        // Configure content based on tier
        switch (tier)
        {
            case "Bronze":
                // Bronze tier features
                break;
            case "Silver":
                // Silver tier features
                break;
            case "Gold":
                // Gold tier features
                break;
        }
    }
    
    private void DisablePremiumContent()
    {
        premiumContent.SetActive(false);
    }
}

Khắc phục sự cố

Sự cố thường gặp

Lỗi “Invalid Client ID”

Vấn đề: bạn gặp lỗi “Invalid Client ID” khi xác thực.

Giải pháp:

1. Kiểm tra Client ID trong Patreon Developer Portal
2. Đảm bảo Client ID được nhập đúng trong Project Settings của Unity
3. Đảm bảo ứng dụng được cấu hình đúng trên Patreon

Sự cố làm mới token

Vấn đề: token không tự động làm mới.

Giải pháp:

1. Kiểm tra kết nối internet
2. Xác minh Client Secret là chính xác
3. Đảm bảo redirect URI khớp chính xác

Sự cố khi build Unity

Vấn đề: plugin chạy trong editor nhưng không chạy trong bản build.

Giải pháp:

1. Đảm bảo mọi phụ thuộc cần thiết đều có trong bản build
2. Kiểm tra cấu hình Patreon đã sẵn sàng cho production
3. Xác minh redirect URI truy cập được từ ứng dụng đã phát hành

Chế độ debug

Bật chế độ debug để có log chi tiết hơn:

PatreonConfig config = new PatreonConfig
{
    // ... other settings
    DebugMode = true
};

Nền tảng hỗ trợ

Tính năng trên nền tảng di động

• Application.identifier: hỗ trợ đầy đủ trên iOS/Android
• Device ID: khóa mã hóa an toàn theo từng thiết bị
• Trình duyệt hệ thống: luồng OAuth native, quay lại ứng dụng
• StreamingAssets: xử lý tệp theo nền tảng
• Lược đồ URL: xử lý callback tùy chỉnh

🔗 Xử lý callback theo nền tảng

Mọi nền tảng (hệ thống middleware hợp nhất)

• Một redirect URI: https://yourdomain.com/api/oauth/redirect?scheme=YOUR_APP_SCHEME
• Lược đồ động: mỗi game có thể dùng lược đồ URI riêng
• Nhận diện nền tảng: tự động nhận diện và định tuyến
• Hỗ trợ toàn diện: chạy trên máy tính, di động và WebGL

Nền tảng di động (Android, iOS, Windows, UWP)

• Deep linking: lược đồ URI tùy chỉnh (YOUR_APP_SCHEME://patreon-callback)
• Chuyển hướng middleware: https://yourdomain.com/api/oauth/redirect → deep link
• Trình duyệt hệ thống: luồng OAuth native, tự động quay lại ứng dụng
• Xác thực state: chống CSRF bằng tham số state

Nền tảng WebGL

• Luồng middleware: dùng https://yourdomain.com/api/oauth/redirect
• Callback JavaScript: giao tiếp postMessage với cửa sổ cha
• Không cần máy chủ: dùng dịch vụ middleware được host sẵn
• Hỗ trợ CORS: xử lý request khác nguồn

Nền tảng desktop (Windows, Mac, Linux)

• Chuyển hướng middleware: https://yourdomain.com/api/oauth/redirect → localhost:3000
• Máy chủ nhúng: HTTP Listener tại localhost:3000
• Luồng loopback: trình duyệt → middleware → localhost → callback ứng dụng
• Không phụ thuộc: cài đặt thuần bằng HttpListener của .NET

📱 Yêu cầu thiết lập trên di động

Thiết lập Android

1. Tạo AndroidManifest.xml trong Assets/Plugins/Android/: ```xml

#### **iOS Setup**
1. **Player Settings** → **Other** → **Configuration**
2. **Add to Supported URL schemes**: `YOUR_APP_SCHEME`
3. Make sure **ios-info.plist** created.
4. **Xcode**: Verify URL scheme registration

#### **Patreon OAuth Client Configuration**
- **All Platforms**: Use single redirect URI with middleware
- **Redirect URI**: `https://yourdomain.com/api/oauth/redirect?scheme=YOUR_APP_SCHEME`
- **Client Type**: Select "Web application" (works for all platforms)
- **Dynamic Scheme**: Each game uses its own URI scheme

### 🌐 **Unified Middleware System**

**Hosted Middleware**: `https://yourdomain.com/api/oauth/redirect`

**Features:**
- **Platform Detection**: Automatic platform detection and routing
- **Dynamic Scheme**: Each game uses its own URI scheme
- **Universal Support**: Works on Desktop, Mobile, and WebGL
- **No Setup Required**: Uses hosted middleware service

**Middleware Workflow:**
1. **Patreon** → `https://yourdomain.com/api/oauth/redirect?scheme=YOUR_APP_SCHEME&code=...&state=...`
2. **Middleware** → Platform detection
3. **Redirect** → Platform-specific callback method

### 🚀 **Usage Examples**

#### **Platform-Specific OAuth Flow**
```csharp
// Automatic platform detection and callback handling
PatreonCallbackManager callbackManager = GetComponent<PatreonCallbackManager>();
callbackManager.StartPatreonOAuthFlow(clientId, state);

// Get platform-specific redirect URI
string redirectUri = callbackManager.GetPlatformRedirectUri();
Debug.Log($"Platform redirect URI: {redirectUri}");

Xử lý deep link trên di động

// Mobile deep link callback (called by system)
PatreonDeepLinkHandler deepLinkHandler = GetComponent<PatreonDeepLinkHandler>();
deepLinkHandler.HandleDeepLinkCallback("myapp.oauth://patreon-callback?code=abc123&state=xyz789");

// Test deep link callback
deepLinkHandler.TestDeepLinkCallback();

Xử lý middleware trên WebGL

// WebGL middleware callback
PatreonWebGLHandler webGLHandler = GetComponent<PatreonWebGLHandler>();
webGLHandler.StartPatreonOAuthFlow(clientId, state);

// Test WebGL callback
webGLHandler.TestWebGLCallback();

Thông tin nền tảng

// Show current platform and callback method
PatreonCallbackManager callbackManager = GetComponent<PatreonCallbackManager>();
callbackManager.ShowPlatformInfo();

// Output:
// 📱 Current Platform: AndroidPlayer
// 📱 Redirect URI: myapp.oauth://patreon-callback
// 🔗 Using deep link callback method

🧪 Kiểm thử

Lệnh kiểm thử

• Test Platform OAuth Flow: kiểm thử luồng OAuth theo nền tảng
• Test Deep Link Callback: kiểm thử xử lý deep link trên di động
• Test WebGL Callback: kiểm thử xử lý middleware trên WebGL
• Show Platform Info: hiển thị thông tin nền tảng hiện tại

Script kiểm thử

• PatreonCallbackManager: kiểm thử theo nền tảng
• PatreonDeepLinkHandler: kiểm thử deep link trên di động
• PatreonWebGLHandler: kiểm thử middleware WebGL
• PatreonMobileTest: kiểm thử tương thích di động

Kiểm thử bảo mật

Plugin có hệ thống kiểm thử bảo mật toàn diện:

1. Thêm component Security Test

// Add PatreonSecurityTest component to any GameObject
// Right-click on GameObject → Add Component → PatreonSecurityTest

2. Chạy kiểm thử bảo mật

// In Inspector, click "Run All Security Tests" or use code:
var securityTest = GetComponent<PatreonSecurityTest>();
securityTest.RunAllTests();

3. Kiểm thử từng component

// Test encryption only
securityTest.TestEncryption();

// Test obfuscation only
securityTest.TestObfuscation();

// Test secure storage only
securityTest.TestSecureStorage();

// Performance test
securityTest.PerformanceTest();

4. Xác minh bảo mật

// Validate entire security system
bool isValid = PatreonSecurity.PatreonSecurity.ValidateSecuritySystem();
Debug.Log($"Security system valid: {isValid}");

Hỗ trợ

Nhận trợ giúp

Nếu bạn gặp sự cố hoặc có câu hỏi:

1. Xem tài liệu - Hầu hết các vấn đề thường gặp đều có ở đây
2. Tham gia cộng đồng Discord của chúng tôi - Nhận trợ giúp từ các nhà phát triển khác và đội ngũ của chúng tôi
3. Liên hệ hỗ trợ - Với sự cố kỹ thuật, hãy gửi cho chúng tôi:
   • Phiên bản Unity
   • Phiên bản plugin
   • Các bước tái hiện lỗi
   • Thông báo lỗi
   • Tệp log

Cộng đồng

Tham gia cộng đồng của chúng tôi để được hỗ trợ và cập nhật:

• Email: [email protected]
• Discord: Tham gia cộng đồng của chúng tôi
• YouTube: DryreL Hub
• YouTube #2: DryreL Software

Cập nhật

Cập nhật các tính năng mới nhất và bản sửa lỗi:

• Unity Asset Store: Tải từ Marketplace (sắp ra mắt)
• Cộng đồng Discord: Tham gia Discord DryreL Hub để được hỗ trợ và cập nhật

TUYÊN BỐ MIỄN TRỪ & TRÁCH NHIỆM

THÔNG BÁO BẢO MẬT QUAN TRỌNG

Plugin này cung cấp mã hóa AES-256 và làm rối mã để giúp bảo vệ thông tin xác thực API Patreon của bạn. Tuy nhiên, BẠN HOÀN TOÀN CHỊU TRÁCH NHIỆM về bảo mật thông tin xác thực của mình và mọi hậu quả phát sinh nếu chúng bị lộ.

Các tính năng bảo mật được cung cấp

• Mã hóa AES-256: để bảo vệ Client Secret
• Làm rối XOR: để làm rối Client ID
• Dẫn xuất khóa nhiều lớp: khóa mã hóa riêng theo nền tảng
• Chống can thiệp: kiểm tra tính toàn vẹn cơ bản
• Nhật ký kiểm tra bảo mật: công cụ giám sát và gỡ lỗi

Trách nhiệm của bạn

• Lưu trữ an toàn: không bao giờ commit PatreonConfig vào hệ thống quản lý phiên bản
• Sử dụng đúng cách: làm theo mọi hướng dẫn bảo mật trong tài liệu này
• Cập nhật thường xuyên: giữ thông tin xác thực luôn mới và thay đổi định kỳ
• Bảo mật môi trường: đảm bảo môi trường phát triển và sản xuất của bạn an toàn
• Kiểm soát truy cập: hạn chế truy cập vào tệp thông tin xác thực và sản phẩm build

Miễn trừ trách nhiệm

DRYREL HUB KHÔNG CHỊU TRÁCH NHIỆM về bất kỳ thiệt hại trực tiếp, gián tiếp, ngẫu nhiên, đặc biệt, hệ quả hoặc mang tính trừng phạt nào, bao gồm nhưng không giới hạn:

• Thiệt hại tài chính: mất doanh thu, gián đoạn kinh doanh hoặc thiệt hại tiền bạc
• Vi phạm bảo mật: truy cập trái phép vào tài khoản hoặc dữ liệu Patreon của bạn
• Lạm dụng API: bên thứ ba sử dụng sai thông tin xác thực của bạn
• Lộ dữ liệu: rò rỉ thông tin nhạy cảm
• Gián đoạn dịch vụ: thời gian ngừng hoạt động hoặc dịch vụ không khả dụng
• Hậu quả pháp lý: mọi vấn đề pháp lý do thông tin xác thực bị lộ

BẠN TỰ CHỊU RỦI RO KHI SỬ DỤNG PLUGIN NÀY. KHÔNG CÓ BẢO ĐẢM NÀO ĐƯỢC ĐƯA RA.

🔧 API V2: vấn đề và giải pháp theo loại tài khoản

⚠️ Các vấn đề đã biết với các loại tài khoản khác nhau

Khi thử nghiệm với các loại tài khoản Patreon khác nhau (nhà sáng tạo và người dùng thường), bạn có thể gặp các vấn đề sau:

1. Không lấy được email

• Vấn đề: trường email trống với người dùng thường
• Nguyên nhân: giới hạn scope OAuth
• Giải pháp: scope OAuth mở rộng giờ bao gồm identity[email]

2. Không lấy được ảnh hồ sơ

• Vấn đề: URL ảnh hồ sơ trống
• Nguyên nhân: khác biệt trong ánh xạ trường API
• Giải pháp: tự động dùng thumb_url nếu image_url trống

3. Thông tin tier/trạng thái sai

• Vấn đề: người dùng thường hiển thị tier “creator”
• Nguyên nhân: phản hồi API không nhất quán giữa các loại tài khoản
• Giải pháp: ghi log và kiểm tra nâng cao (xem cảnh báo trong console)

4. Không lấy được liên kết mạng xã hội

• Vấn đề: liên kết YouTube, Twitter, Facebook trống
• Nguyên nhân: quyền truy cập trường API bị giới hạn với người dùng thường
• Giải pháp: yêu cầu thêm trường trong lệnh gọi API

🔍 Thông tin gỡ lỗi

Plugin giờ có log gỡ lỗi đầy đủ. Hãy xem Console của Unity để thấy:

• 🔧 === USER DATA DEBUG === - Phân tích đầy đủ dữ liệu người dùng
• 🔧 Email not available - Cảnh báo giới hạn scope
• 🔧 Normal user has tier_title - Sự không nhất quán giữa các loại tài khoản

📋 Danh sách kiểm tra

Khi thử nghiệm với các loại tài khoản khác nhau:

1. Thử với tài khoản nhà sáng tạo:
   • ✅ Phải lấy được email
   • ✅ Phải lấy được ảnh hồ sơ
   • ✅ Thông tin tier phải chính xác
   • ✅ Liên kết mạng xã hội có thể có
2. Thử với tài khoản người dùng thường:
   • ⚠️ Email có thể không có (tùy scope)
   • ✅ Phải lấy được ảnh hồ sơ (có phương án dự phòng)
   • ⚠️ Thông tin tier có thể sai (được ghi thành cảnh báo)
   • ⚠️ Liên kết mạng xã hội có thể không có

🛠️ Scope OAuth mở rộng

Plugin giờ yêu cầu các scope mở rộng:

identity identity[email] identity.memberships campaigns

Điều này giúp truy cập dữ liệu người dùng tốt hơn trên nhiều loại tài khoản.

🔧 Kiểm tra & sửa dữ liệu API

Lưu ý quan trọng: plugin có kiểm tra dữ liệu phía client và sửa các điểm không nhất quán đã biết của Patreon API V2. Điều này cần thiết vì:

1. Vấn đề dữ liệu API: Patreon API V2 đôi khi trả về dữ liệu sai cho người dùng thường (ví dụ hiển thị tier “Creator” cho người dùng thường)
2. Dữ liệu mâu thuẫn: API có thể trả về các giá trị mâu thuẫn (ví dụ patron_status: "not_patron" nhưng is_patron: true)
3. Lẫn loại tài khoản: dữ liệu người dùng và nhà sáng tạo đôi khi bị lẫn trong phản hồi API
4. Vấn đề trạng thái theo dõi: trường is_follower không đáng tin cậy và có thể trả về false dù người dùng đang theo dõi

Plugin làm gì:

• ✅ Kiểm tra mọi dữ liệu người dùng từ API
• ✅ Tự động sửa các điểm không nhất quán đã biết
• ✅ Ghi log các vấn đề API để gỡ lỗi
• ✅ Cung cấp giá trị dự phòng khi cần
• ✅ Cảnh báo về các trường không đáng tin cậy như is_follower

Các log console cần chú ý:

• 🔧 API ISSUE: Normal user has incorrect tier_title: Creator - fixing
• 🔧 API ISSUE: is_follower is false - this might be incorrect due to Patreon API V2 limitations
• 🔧 API DATA ISSUES DETECTED AND FIXED - This indicates Patreon API V2 data inconsistencies

Giới hạn API đã biết:

• is_follower: trường này không đáng tin cậy trong Patreon API V2 và có thể trả về false dù người dùng đang theo dõi nhà sáng tạo
• Phát hiện người theo dõi: để phát hiện chính xác cần gọi thêm API tới endpoint campaigns/pledges
• Tham khảo: xem Patreon API Guide để biết cách phát hiện người theo dõi đúng

Cách này đảm bảo dữ liệu người dùng đáng tin cậy dù API không nhất quán.