Skip to main content

ShopShip

info

Gitlab: https://gitlab.winds.vn/shopship/shopship_app_customer

Requirements​

Trước khi chạy project, cần cài đặt các công cụ sau:

Node.js​

Cài đặt Node.js version 16 trở lên.

Tải tại:

https://nodejs.org/en/download/

Kiểm tra version:

node -v

Khuyến nghị sử dụng nvm để quản lý nhiều version Node.js trên cùng một máy.

Yarn​

Cài đặt Yarn version 1.22.19.

Kiểm tra version:

yarn -v

Tài liệu cài đặt:

https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable

Running the development server

1. Cấu hình biến môi trường​

Chỉnh sửa file .env trong project.

Khi chạy mini-app local, hệ thống sẽ sử dụng các biến môi trường này.

APP_ID=2157220094284221359
VITE_APP_ID=2157220094284221359
VITE_DEEPLINK_APP=https://zalo.me/s/2157220094284221359/
VITE_SECRET_KEY_APP=C87V9JRHiTN2R6ISWgIJ
VITE_PRIVATE_KEY=f757fb6e9cb11e02a871a37fbced9f6b
VITE_APP_NAME=Taxi Thuan Phat
VITE_BASE_API_URL=https://dev.admin.shopship.winds.vn
VITE_BASE_API_URL_PRO=https://admin.shopship.winds.vn
VITE_BASE_API_URL_STAGING=https://staging.admin.shopship.winds.vn
VITE_BASE_API_URL_STAGING2=https://staging2.admin.shopship.winds.vn
VITE_APP_VERSION=1
VITE_TESTING_VERSION=1
VITE_MIN_ZALO_VER_IOS=584
VITE_MIN_ZALO_VER_ANDROID=12100729
VITE_COLORPRIMARY=#ee4e1f
ZMP_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIzNzY3MzI3MTA4OTA4Mjc0ODYxIiwiYXBwSWQiOiIyMTU3MjIwMDk0Mjg0MjIxMzU5IiwiaXNzIjoiYXV0aDAiLCJleHAiOjE3NzMxMTQ5MjV9.1sIDArjZG636oc053l-La6GWnuCOTXRkLPT4TTkUUxM

Giải thích các biến môi trường quan trọng​

APP_ID / VITE_APP_ID​

Dùng để xác định Mini App trên hệ thống Zalo Mini App.

Có thể lấy tại:

https://miniapp.zaloplatforms.com/miniapp/2755983158715529005/statistic/overview

VITE_SECRET_KEY_APP​

Secret key của ứng dụng, dùng cho một số chức năng xác thực.

Có thể lấy tại:

https://developers.zalo.me/app/842407967173129371/settings

VITE_PRIVATE_KEY​

Key dùng cho cấu hình bảo mật và tích hợp các chức năng liên quan trong mini-app.

Có thể lấy tại:

https://miniapp.zaloplatforms.com/miniapp/2755983158715529005/payment/settings

VITE_COLORPRIMARY​

Màu chủ đạo của ứng dụng.

Với cấu hình hiện tại:

VITE_COLORPRIMARY=#ee4e1f

ứng dụng sẽ sử dụng màu #ee4e1f làm màu primary.

VITE_APP_VERSION​

Dùng để quyết định môi trường API của phiên bản đang publish cho khách.

Giá trị này cần được đồng bộ với version được cấu hình trên hệ thống quản trị.

2. Cài đặt dependencies​

Trong thư mục chứa file package.json, chạy lệnh:

yarn install

3. Chạy project local​

Để chạy project local thông thường, dùng lệnh:

yarn dev

Khi chạy local bằng yarn dev, ứng dụng sẽ sử dụng cấu hình local/development theo thiết lập hiện tại của project.

Deploy

Trước khi deploy mini-app, cần đăng nhập Zalo Mini App CLI bằng lệnh:

zmp login

Lệnh này dùng để xác thực tài khoản trước khi thực hiện deploy.

Build QR để test theo môi trường​

Tùy vào môi trường muốn build QR, sử dụng một trong các lệnh sau:

Môi trường development​

yarn deploy_dev

Môi trường staging​

yarn deploy_stag

Môi trường production​

yarn deploy_pro

Cơ chế chọn API theo version publish

Ứng dụng hoạt động với logic sau:

Number(res?.data?.miniAppVersion) >= import.meta.env.VITE_APP_VERSION
  ? res?.data?.baseProdApiUrl
  : import.meta.env.VITE_BASE_API_URL_STAGING;

Ý nghĩa​

  • Nếu version mini-app trên hệ thống (res?.data?.miniAppVersion) lớn hơn hoặc bằng VITE_APP_VERSION thì app sẽ gọi API production từ:
res?.data?.baseProdApiUrl;
  • Nếu không thỏa điều kiện trên, app sẽ gọi API staging từ:
import.meta.env.VITE_BASE_API_URL_STAGING;

Lưu ý quan trọng​

Trước khi publish app cho khách, cần:

  1. Đổi số version trên web Super Admin trước
  2. Sau đó mới publish app

Nếu không thực hiện đúng thứ tự này, app có thể bị trỏ sai môi trường API sau khi publish.

Lưu ý

Đảm bảo các biến môi trường được cấu hình chính xác trước khi chạy hoặc deploy project, đặc biệt là:

  • APP_ID
  • VITE_SECRET_KEY_APP
  • VITE_PRIVATE_KEY
  • VITE_APP_VERSION

Ngoài ra, trước khi deploy cần chắc chắn đã đăng nhập CLI bằng lệnh:

zmp login

Nếu chưa đăng nhập, quá trình deploy có thể thất bại.