# Tài liệu Đặc tả Hệ thống Addon API — NG Player Tài liệu này hướng dẫn chi tiết cách xây dựng một cổng API dịch vụ (Addon) tương thích với trình phát đa phương tiện **NG Player**. Hệ thống Addon cho phép bên thứ ba tích hợp nguồn dữ liệu phim/truyền hình, hỗ trợ duyệt danh mục (Khám phá), tìm kiếm nâng cao và truyền phát trực tiếp (Streaming). --- ## 1. Cơ chế hoạt động của Addon Addon trong NG Player bản chất là một **HTTP JSON API Server**. Khi người dùng cài đặt Addon bằng cách nhập địa chỉ URL (ví dụ: `https://myaddon.com`), ứng dụng sẽ thực hiện: 1. Gửi request `GET https://myaddon.com/manifest.json` để kiểm tra thông tin cấu hình Addon và đăng ký bộ lọc (Genres, Countries, Years...). 2. Khi người dùng vào tab **Khám phá**, gọi `GET https://myaddon.com/api/discover`. 3. Khi người dùng bấm xem chi tiết phim, gọi `GET https://myaddon.com/api/detail?id=`. 4. Khi người dùng tìm kiếm, gọi `GET https://myaddon.com/api/search?q=&page=...`. ### Yêu cầu CORS (Bắt buộc) Vì ứng dụng di động thực hiện gọi API từ thiết bị, máy chủ Addon **phải hỗ trợ CORS** bằng cách phản hồi các tiêu đề (headers) sau đối với mọi endpoint: ```http Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: * ``` *(Với phương thức `OPTIONS` tiền kiểm tra - preflight, máy chủ chỉ cần trả về HTTP status 200).* --- ## 2. Đặc tả các API Endpoints ### 2.1 Manifest Endpoint (`/manifest.json`) Cung cấp định danh Addon, các danh mục chính và danh sách bộ lọc tìm kiếm. - **Request**: `GET /manifest.json` - **Response Format (JSON)**: ```json { "id": "com.myaddon.uniqueid", "name": "Tên Addon Hiển Thị", "version": "1.0.0", "description": "Mô tả ngắn gọn về Addon của bạn.", "catalogs": [ { "id": "movie", "name": "Phim lẻ", "type": "movie" }, { "id": "tv", "name": "Phim bộ", "type": "tv" } ], "filters": { "formats": [ { "id": "movie", "name": "Phim lẻ" }, { "id": "tv", "name": "Phim bộ" } ], "genres": [ { "id": "28", "name": "Hành động" }, { "id": "35", "name": "Hài hước" } ], "countries": [ { "id": "US", "name": "Mỹ" }, { "id": "VN", "name": "Việt Nam" } ], "years": [ { "id": "2026", "name": "2026" }, { "id": "2025", "name": "2025" } ], "audios": [ { "id": "dubbing", "name": "Lồng tiếng" }, { "id": "voiceover", "name": "Thuyết minh" } ] } } ``` --- ### 2.2 Discover Endpoint (`/api/discover`) Trả về danh sách phim hiển thị ở màn hình trang chủ Khám phá (bao gồm các Banner nổi bật ở trên cùng và các dòng danh sách cuộn ngang ở dưới). - **Request**: `GET /api/discover` - **Response Format (JSON)**: ```json { "banner": [ { "id": "movie-123", "title": "Tên gốc của phim", "title_vi": "Tên tiếng Việt của phim", "backdrop_path": "https://domain.com/anh-nen-16-9.jpg", "poster_path": "https://domain.com/anh-poster-2-3.jpg", "overview": "Mô tả tóm tắt nội dung phim...", "rating": 8.5, "year": 2026, "type": "movie" } ], "sections": [ { "title": "Phim xem nhiều nhất", "category_id": "most-watched", "items": [ { "id": "movie-456", "title": "Tên phim", "title_vi": "Tên tiếng Việt", "backdrop_path": "https://domain.com/backdrop.jpg", "poster_path": "https://domain.com/poster.jpg", "rating": 7.9, "year": 2025, "type": "movie" } ] } ] } ``` --- ### 2.3 Detail Endpoint (`/api/detail`) Trả về thông tin đầy đủ, danh sách diễn viên, phim đề xuất liên quan và **quan trọng nhất là các tệp phát video**. - **Request**: `GET /api/detail?id=` - **Response Format (JSON)**: ```json { "media": { "id": "movie-123", "title": "Tên phim", "title_vi": "Tên tiếng Việt", "overview": "Mô tả nội dung chi tiết...", "backdrop_path": "https://domain.com/backdrop.jpg", "poster_path": "https://domain.com/poster.jpg", "rating": 8.5, "year": 2026, "duration": 120, "type": "movie" }, "files": [ { "id": "file-opt-1", "name": "Tập 1 - Bản HD", "url": "https://stream.server.com/live/movie.m3u8", "subtitle": "https://stream.server.com/subs/vietnamese.vtt", "size": "1.2 GB" } ], "genres": [ { "id": 28, "name": "Hành động" } ], "cast": [ { "name": "Tên diễn viên", "character": "Tên vai diễn", "profile_path": "https://domain.com/avatar.jpg" } ], "networks": [ { "name": "Tên đài phát (HBO/Netflix...)", "logo_path": "" } ], "companies": [ { "name": "Hãng sản xuất", "logo_path": "" } ], "collectionMovies": [ { "id": "movie-789", "title": "Phim tương tự", "poster_path": "https://domain.com/poster2.jpg", "rating": 7.5, "year": 2024, "type": "movie" } ] } ``` --- ### 2.4 Search Endpoint (`/api/search`) Thực hiện truy vấn tìm kiếm tự do kết hợp các bộ lọc và sắp xếp phân trang. - **Request Query Parameters**: - `q` hoặc `key`: Từ khóa tìm kiếm tự do (ví dụ: `avatar`). - `page`: Số trang hiện tại (mặc định: `1`). - `limit`: Số lượng phim trên mỗi trang (mặc định: `18` hoặc `36`). - `type`: Định dạng phát (`movie` hoặc `tv`). - `genre`: Lọc theo thể loại ID. - `country`: Lọc theo mã quốc gia (ví dụ: `US`, `VN`). - `year`: Lọc theo năm phát hành hoặc khoảng năm (ví dụ: `2026`, `2020-2023`). - `vietnamese`: Lọc theo thuyết minh/phụ đề. - `sort`: Tiêu chí sắp xếp (`year_desc`, `year_asc`, `alpha_asc`, `alpha_desc`). - `cast_id`: Lọc theo ID diễn viên. - `network_id`: Lọc theo ID đài phát. - `company_id`: Lọc theo ID hãng sản xuất. - **Response Format (JSON)**: ```json { "results": [ { "id": "movie-123", "title": "Tên phim", "title_vi": "Tên tiếng Việt", "backdrop_path": "https://domain.com/backdrop.jpg", "poster_path": "https://domain.com/poster.jpg", "rating": 8.5, "year": 2026, "type": "movie" } ] } ``` --- ## 3. Hướng dẫn thử nghiệm Addon trên NG Player 1. Khởi động máy chủ API của bạn (ví dụ chạy trên máy local tại cổng `3000`). 2. Mở ứng dụng **NG Player** trên di động / máy ảo. 3. Chuyển sang tab **Cài đặt** -> chọn **Tiện ích mở rộng (Addon)**. 4. Bấm nút **Thêm Addon mới** và nhập địa chỉ Addon của bạn (ví dụ: `http://localhost:3000`). *(Lưu ý: Nếu chạy trên thiết bị thật, hãy dùng địa chỉ IP nội bộ của máy tính dạng `http://192.168.1.x:3000` thay cho localhost).* 5. Ứng dụng sẽ tự động gọi file `/manifest.json` để kiểm tra và kích hoạt tab **Khám phá** chứa các nội dung do Addon của bạn cung cấp!