iFrame API · Trợ giúp Measure Map Online

Hiển thị một trong các dự án của bạn dưới dạng bản đồ trực tiếp trên trang web riêng, với đơn vị, kiểu bản đồ và giao diện phù hợp với trang của bạn.

iFrame API đưa bản đồ của một dự án lên trang web của bạn. Khách truy cập thấy bản đồ vệ tinh cùng các số đo của bạn và có thể di chuyển trên đó, không cần tài khoản và không rời khỏi trang của bạn. Bạn chọn dự án, đơn vị, kiểu bản đồ và giao diện màu.

Trước khi bắt đầu#

Một khóa API live có quyền Bản đồ nhúng. Xem khóa API.
Một dự án mà khách truy cập được phép xem: của bạn hoặc của tài khoản khác, được chia sẻ ở mức Chỉ xem hoặc Công khai. Một dự án Riêng tư chỉ hiển thị nếu thuộc tài khoản khác và chủ sở hữu đã ủy quyền cho bạn (xem dự án riêng tư của khách hàng); dự án riêng tư của chính bạn thì không bao giờ hiển thị. Xem những dự án nào có thể nhúng.
Tùy chọn, hạn chế trang web cho khóa, để bản nhúng chỉ hoạt động trên các trang web của bạn. Xem khóa API.

Tạo mã nhúng#

Nhà phát triển > Nhúng bản đồ tạo mã giúp bạn bằng khóa live của bạn: chọn dự án, chọn giao diện, đơn vị, loại bản đồ và kích thước, kiểm tra Xem trước trực tiếp, rồi sao chép Mã nhúng. Nếu dự án ở chế độ riêng tư, phần này sẽ cho biết và đề nghị Chuyển sang chỉ xem. Xem lấy mã nhúng để biết từng bước.

Nhúng một bản đồ với dự án đã chọn và bản xem trước trực tiếp

Mã mang theo khóa của bạn, nên nó tiếp tục hoạt động cho đến khi bạn thay khóa. Phần này cảnh báo bạn khi khóa làm được nhiều hơn Bản đồ nhúng, vì bất kỳ ai cũng đọc được nó trong mã nguồn trang của bạn, và khi khóa không có hạn chế trang web. Chỉ Xem trước trực tiếp dùng token có thời hạn ngắn. Xem khóa hay token.

Địa chỉ nhúng#

Bản nhúng là một <iframe> có địa chỉ bắt đầu bằng https://app.measuremaponline.com/iframe_api, theo sau là các tham số sau:

Tham số	Cần không	Giá trị
`pid`	bắt buộc	ID của dự án: phần sau `/p/` trong địa chỉ của dự án trong ứng dụng. Chủ sở hữu có thể sao chép nó ở cuối tổng quan của dự án, và nhấp vào tên dự án trong bản đồ nhúng cũng sao chép nó.
`key`	`key` hoặc `token`	Khóa API của bạn.
`token`	`key` hoặc `token`	Một token từ máy chủ của bạn (xem bên dưới).
`ms`	tùy chọn	Đơn vị: `metric` hoặc `imperial`. Nếu không có, khách truy cập ở Hoa Kỳ thấy đơn vị Anh-Mỹ và mọi người khác thấy hệ mét.
`maptype`	tùy chọn	`satellite` (mặc định), `map`, `hybrid` hoặc `terrain`.
`theme`	tùy chọn	`auto` (mặc định: theo cài đặt hệ thống của chính khách truy cập), `light` hoặc `dark`.

Một ví dụ tối giản#

<iframe src="https://app.measuremaponline.com/iframe_api?pid=YOUR_PROJECT_ID&key=YOUR_API_KEY&maptype=satellite&theme=auto"
  title="YOUR_PROJECT_NAME" width="500" height="500" style="border:0" allow="fullscreen"></iframe>

Hãy thay YOUR_PROJECT_ID, YOUR_API_KEY và YOUR_PROJECT_NAME (trình đọc màn hình sẽ đọc title lên), và đặt chiều rộng, chiều cao cho vừa với trang của bạn.

Khóa hay token#

Với key, như trong mã mà phần Nhúng bản đồ cung cấp, bản nhúng tiếp tục hoạt động chừng nào khóa còn hoạt động, trên các trang web mà hạn chế của khóa cho phép. Khi đó khóa của bạn hiển thị trong mã nguồn trang, nên:

chỉ dùng khóa có quyền Bản đồ nhúng;
giới hạn nó cho các trang web của bạn;
khi bạn thay khóa, hãy cập nhật các trang của bạn trong vòng 24 giờ khóa cũ còn hoạt động (khóa tạo trước khi có cài đặt quyền truy cập giữ ngày bạn được thông báo).

Với token, khóa vẫn nằm trên máy chủ của bạn. Cách này phù hợp với các bản nhúng mà máy chủ của bạn ghi vào trang cho mỗi lượt truy cập: trước khi hiển thị trang, máy chủ xin REST API một token và đặt nó vào địa chỉ của iframe:

POST https://api.measuremaponline.com/api/v2/auth/iframe/token, với khóa của bạn trong header Authorization, trả về một token có hiệu lực 60 phút;
POST https://api.measuremaponline.com/api/v2/auth/token cũng làm như vậy và nhận tham số duration tính bằng giây, tối đa 24 giờ. Phản hồi cho biết khi nào token hết hạn.

Tài khoản của bạn có thể lấy tối đa 600 token mỗi giờ. Hãy dùng khóa live: bản nhúng chỉ hiển thị dự án live, nên token tạo bằng khóa sandbox không mở được bản đồ. Xem tài liệu tham khảo API.

Khách truy cập làm được gì#

Khách truy cập có thể kéo và thu phóng bản đồ, đọc số đo của các hình bạn vẽ và đọc bình luận của dự án. Họ có thể thêm bình luận khi dự án cho phép mọi người bình luận, và nhấp vào tên dự án sẽ sao chép ID của nó. Họ không thể thay đổi gì khác: việc chỉnh sửa bị tắt bên trong bản nhúng, bất kể mức truy cập của dự án. Ngoại lệ duy nhất là dự án Open Guest trên gói Open Guest, nơi khách truy cập tự đo cho mình.

Khi bản đồ không xuất hiện#

Trong hầu hết trường hợp, bản đồ hiển thị một thông báo cho biết lý do: xem khi bản đồ hiển thị một thông báo. Hãy kiểm tra lần lượt:

Địa chỉ có một token đã hết hạn. Token có hiệu lực 60 phút trừ khi máy chủ của bạn yêu cầu lâu hơn. Hãy sao chép lại mã từ Nhúng bản đồ, nơi dùng khóa của bạn, hoặc để máy chủ của bạn lấy token mới cho mỗi lượt truy cập (xem ở trên).
Dự án ở chế độ riêng tư. Nếu là của bạn, hãy đặt thành Chỉ xem hoặc Công khai, hoặc nhấn Chuyển sang chỉ xem trong Nhúng bản đồ. Nếu là của khách hàng, họ có thể ủy quyền cho bạn từ bản đồ, hoặc bạn có thể hỏi họ trong Dự án riêng tư.
Gói của dự án đã kết thúc: gói của chủ sở hữu, hoặc với dự án của một tổ chức, gói của tổ chức. Dự án hiển thị lại khi gói được gia hạn.
Trang web không được phép. Nếu khóa có hạn chế trang web, trang hiển thị bản nhúng phải thuộc một trong các trang web đó. Một số trình duyệt và trang web ẩn việc bản nhúng nằm trên trang nào; khi đã đặt hạn chế, bản nhúng như vậy bị từ chối.
Khóa đã bị thay. Khóa cũ ngừng hoạt động 24 giờ sau khi khóa mới được tạo, hoặc ngay lập tức nếu nó bị thu hồi.
Khóa là khóa sandbox. Bản nhúng chỉ hoạt động với khóa live và dự án live.
Gói đăng ký không còn hiệu lực, hoặc quyền truy cập API bị tạm ngưng: phần Khóa API sẽ cho biết.