App manifest

ทุกฟิลด์ของ awhere-app.json ซึ่งเป็นไฟล์ที่แอปใช้บอกว่าตัวเองคืออะไร ฟิลด์ไหนจำเป็น และแต่ละฟิลด์หมายถึงอะไร

App manifest คือไฟล์ที่แอปใช้บอกว่าตัวเองคืออะไร ได้แก่ ชื่อ ผู้เผยแพร่ ที่อยู่ที่แอปให้บริการ วิธีลงชื่อเข้าใช้ และสิทธิ์ที่แอปขอ ไฟล์นี้ชื่อ awhere-app.json และแอปจะถูกติดตั้งจาก manifest ของมัน

การติดตั้งแอปทำสองอย่าง คือบันทึกแถวของแอปหนึ่งแถวซึ่งเก็บ manifest ไว้ตามที่ติดตั้ง และสร้าง OAuth client ของแอป การถอนการติดตั้งจะเอาทั้งสองอย่างออก และถ้าติดตั้งอีกครั้ง ระบบจะคืน client เดิมพร้อม secret เดิม

แอปให้บริการ manifest ของตัวเองที่ awhere-app.json ใต้ที่อยู่ของแอป เมื่อผู้ดูแลระบบดูตัวอย่างก่อนติดตั้ง แพลตฟอร์มจะขอไฟล์นี้จากแอป และแจ้งเตือนถ้าแอปไม่ตอบ อ่านไฟล์ไม่ได้ หรือ id กับ version ในไฟล์ไม่ตรงกับ manifest ที่กำลังติดตั้ง

ตอนนี้ติดตั้งได้เฉพาะ manifest แบบ official ที่ฝังมากับ image ของแพลตฟอร์มเท่านั้น manifest ที่ตั้ง "channel": "community" ถูกต้องตามรูปแบบ แต่แพลตฟอร์มจะปฏิเสธการติดตั้ง จนกว่าแพลตฟอร์มจะสามารถแสดงให้ผู้ใช้เห็นว่าแอปขอสิทธิ์อะไร และบังคับใช้สิทธิ์นั้นได้

ตัวอย่าง

นี่คือ manifest ของ Map Studio ตามที่แอปเผยแพร่ ใช้ฟิลด์ที่จำเป็นทั้งหมดและฟิลด์ที่ไม่บังคับอีกบางส่วน

{
  "manifestVersion": 1,
  "id": "map-studio",
  "name": "Map Studio",
  "shortName": "Map",
  "description": "Web maps with layers, styles and measurement.",
  "locales": {
    "th": { "description": "สร้างแผนที่เว็บที่มีชั้นข้อมูล รูปแบบการแสดงผล และเครื่องมือวัด" }
  },
  "publisher": {
    "name": "MAPBOSS Co., Ltd.",
    "url": "https://mapboss.co.th"
  },
  "channel": "official",
  "version": "1.0.0",
  "categories": ["maps"],
  "path": "/map-studio/",
  "oauth": {
    "scopes": ["*"]
  }
}

ฟิลด์ที่จำเป็น

manifest ที่ขาดฟิลด์ใดฟิลด์หนึ่งด้านล่างจะถูกปฏิเสธ และเหตุผลที่แจ้งจะระบุชื่อฟิลด์นั้น

ฟิลด์	ค่า	ความหมาย
`manifestVersion`	ตัวเลข `1`	เวอร์ชันของรูปแบบไฟล์นี้ ไม่รับค่าอื่น
`id`	ตัวอักษรภาษาอังกฤษพิมพ์เล็ก ตัวเลข และขีดกลาง ยาวไม่เกิน 64 ตัวอักษร	App id ซึ่งเป็นชื่อเดียวของแอป และเป็นทั้งคีย์ของการติดตั้งและ OAuth client ที่แอปใช้ลงชื่อเข้าใช้ manifest แบบ community ใช้จุดคั่นระหว่างส่วนของชื่อได้ด้วย เช่น `acme.reports`
`name`	ข้อความ ยาวไม่เกิน 60 ตัวอักษร	ชื่อที่ Marketplace แสดง
`version`	`1.2.3` และอาจต่อด้วย `-` หรือ `+` ตามด้วยส่วนต่อท้าย เช่น `1.2.3-beta.1`	เวอร์ชันของแอป
`channel`	`official` หรือ `community`	ใครเป็นผู้สร้างแอป แอป official สร้างโดย MAPBOSS ส่วนแอป community สร้างโดยบุคคลอื่น
`publisher.name`	ข้อความ	ผู้เผยแพร่แอป ดู `publisher`
`path` หรือ `url`	ดู ที่อยู่ที่แอปให้บริการ	ต้องมีอย่างน้อยหนึ่งในสองอย่าง
`oauth.scopes`	รายการข้อความ ซึ่งเป็นรายการว่างได้	สิทธิ์ที่แอปขอ ดู `oauth`

ฟิลด์ที่ไม่บังคับ

ฟิลด์	ค่า	ความหมาย
`shortName`	ข้อความ ยาวไม่เกิน 12 ตัวอักษร	ข้อความที่ Launcher แสดงใต้ไอคอน ถ้าไม่มีจะใช้ `name` เต็ม
`description`	ข้อความ	คำอธิบายสั้น ๆ ของแอป แสดงใน Marketplace
`icon`	ที่อยู่ `https` พาธแบบสัมพัทธ์ หรือ SVG data URI ที่ขึ้นต้นด้วย `data:image/svg+xml;base64,`	รูปของแอปใน Marketplace พาธแบบสัมพัทธ์จะอ้างอิงจากที่อยู่ของแอปเมื่อที่อยู่นั้นมีโฮสต์ นอกจากนั้นจะใช้โลโก้ของแพลตฟอร์มแทน
`categories`	รายการข้อความ	กลุ่มสำหรับตัวกรองใน Marketplace ค่า `admin` `files` `data` `forms` `maps` และ `apps` มีคำเรียกของตัวเองใน Marketplace ค่าอื่นจะแสดงตามที่เขียน โดยขึ้นต้นด้วยตัวพิมพ์ใหญ่
`screenshots`	รายการของ `{ "src": …, "caption": … }`	`src` เป็นที่อยู่ `https` หรือพาธแบบสัมพัทธ์ ส่วน `caption` เป็นข้อความที่ไม่บังคับ
`homepage`	ที่อยู่ `https`	หน้าเว็บของแอป
`support`	ที่อยู่ `https`	ที่ขอความช่วยเหลือ
`locales`	อ็อบเจกต์ที่ใช้ภาษาเป็นคีย์ ดู `locales`	ข้อความในภาษาอื่น
`requires.platform`	ข้อความ	แพลตฟอร์มที่แอปต้องการ

คีย์ที่ไม่อยู่ในสองตารางนี้จะถูกตัดทิ้ง และ image ถูกสงวนไว้และไม่มีผลใด ๆ path กับ url อยู่ในหัวข้อถัดไป ส่วนคีย์ภายใน publisher และ oauth อยู่ในหัวข้อของตัวเอง

ที่อยู่ที่แอปให้บริการ

path หรือ url หรือทั้งสองอย่าง บอกว่าที่อยู่ของแอปคืออะไร ต้องมีอย่างน้อยหนึ่งอย่าง

ฟิลด์	ค่า	ความหมาย
`path`	ขึ้นต้นและลงท้ายด้วย `/` ไม่มีช่องว่าง `?` `#` และส่วนที่เป็น `.` หรือ `..` เช่น `/map-studio/`	แอปอยู่บนโฮสต์เดียวกับแพลตฟอร์ม ที่อยู่ของแอปคือที่อยู่ของแพลตฟอร์ม (`PLATFORM_URL`) ตามด้วยพาธนี้
`url`	ที่อยู่ `https`	แอปอยู่ที่อื่น ถ้ามีทั้งสองอย่าง `url` จะถูกใช้

ผู้ดูแลระบบกำหนดที่อยู่อื่นให้การติดตั้งหนึ่งครั้งได้ จะเป็นที่อยู่ http หรือ https หรือพาธที่ลงท้ายด้วย / ก็ได้ ที่อยู่นั้นถูกเก็บไว้กับการติดตั้ง ส่วน manifest ยังเป็นตามเดิม

`publisher`

ฟิลด์	จำเป็นหรือไม่	ค่า
`publisher.name`	จำเป็น	ข้อความ
`publisher.url`	ไม่บังคับ	ที่อยู่ `https`
`publisher.email`	ไม่บังคับ	ที่อยู่อีเมล

`oauth`

แอปลงชื่อเข้าใช้ผ่านแพลตฟอร์มในฐานะ OAuth client ที่มี id เป็น App id แพลตฟอร์มสร้าง client นี้จาก manifest เอง จึงเลือก client id อื่นใน manifest ไม่ได้ และไม่อนุญาตให้ใส่ oauth.clientId

ฟิลด์	จำเป็นหรือไม่	ค่า	ความหมาย
`oauth.scopes`	จำเป็น	รายการข้อความ	สิทธิ์ที่แอปขอ Marketplace แสดงรายการนี้ใต้หัวข้อ "What this app can do" ค่า `*` อ่านว่าแอปทำงานในนามผู้ที่ลงชื่อเข้าใช้ด้วยสิทธิ์ของผู้นั้น สิทธิ์ที่ Marketplace รู้จักจะมีคำอธิบายเป็นภาษาคน และสิทธิ์อื่นจะแสดงเป็น "Access named …" รายการว่างอ่านว่าแอปไม่ขอสิทธิ์เข้าถึงใด ๆ
`oauth.redirectPaths`	ไม่บังคับ	รายการพาธแบบสัมพัทธ์	ที่ที่การลงชื่อเข้าใช้ของแอปกลับมา ใต้ที่อยู่ของแอป ถ้าไม่ระบุจะเป็น `oauth/awhere-callback` Log Monitoring ตั้งเป็น `oauth-callback`
`oauth.redirectUris`	ไม่บังคับ	รายการที่อยู่ `https`	ที่อยู่เต็มสำหรับการลงชื่อเข้าใช้ที่กลับมานอกที่อยู่ของแอป
`oauth.origins`	ไม่บังคับ	รายการ origin แบบ `https` เช่น `https://reports.example.com` โดยไม่มีพาธ	เก็บไว้ใน OAuth client ของแอปเป็นค่า `origins`

redirectPaths จะกลายเป็นที่อยู่เต็มก็ต่อเมื่อที่อยู่ของแอปมีโฮสต์ ถ้าที่อยู่เป็นเพียงพาธ จะนับเฉพาะ redirectUris แอป official ขอ ["*"] และแพลตฟอร์มไม่บังคับใช้ scope กับ client แบบ official

`locales`

locales เป็นอ็อบเจกต์ที่ใช้ภาษาเป็นคีย์ เช่น th ค่าของแต่ละภาษามีได้เฉพาะ name shortName และ description ซึ่งเป็นข้อความทั้งหมด โดย shortName ยาวไม่เกิน 12 ตัวอักษร เมื่อ Marketplace แสดงเป็นภาษาที่มีรายการนี้ ข้อความทั้งสามจะแทนที่ข้อความด้านบน แอป official ทุกตัวใช้วิธีนี้ใส่คำอธิบายภาษาไทย

"locales": {
  "th": { "description": "ตั้งค่าแพลตฟอร์ม รวมถึงบทบาท ผู้ใช้ กลุ่ม OAuth client และคีย์ API" }
}

แพลตฟอร์มใช้แต่ละฟิลด์อย่างไรในตอนนี้

Launcher แสดง shortName (หรือ name) และรูปของแอป รูปนั้นคือโลโก้ที่อัปโหลดไว้ใน client ของแอป ถ้าไม่มีจะเป็น icon.svg ใต้ที่อยู่ของแอป
Marketplace แสดง name description locales publisher.name version channel categories icon และ oauth.scopes และกรองตาม categories
screenshots homepage support และ requires.platform ถูกตรวจและเก็บไว้กับการติดตั้ง แต่ยังไม่มีหน้าจอใดแสดง และยังไม่มีอะไรนำ requires.platform ไปเทียบกับแพลตฟอร์ม

แอป official

แอป official ทั้งเก้าตัวมี manifest ที่ฝังไว้ใน image ของแพลตฟอร์ม manifest แบบ official ทุกตัวถูกตรวจก่อนฝัง และระบบจะปฏิเสธ manifest ที่ manifestVersion ไม่ใช่ 1 ที่ id ซ้ำหรือไม่ได้ประกอบด้วยตัวอักษรพิมพ์เล็ก ตัวเลข และขีดกลาง ที่ channel ไม่ใช่ official ที่ path ไม่ได้ขึ้นต้นและลงท้ายด้วย / ที่ shortName ยาวเกิน 12 ตัวอักษร หรือที่ categories มีค่าอื่นนอกจาก maps data forms apps files และ admin

manifest แบบ official ไม่เก็บ icon ไว้ในไฟล์ แพลตฟอร์มจะนำ icon.svg ของแอปไปเก็บคู่กับ manifest ที่ฝังไว้เป็น SVG data URI และ icon ที่เขียนไว้ใน manifest จะถูกละเลย

ตัวอย่างคัดลอกลิงก์ของหัวข้อ

ฟิลด์ที่จำเป็นคัดลอกลิงก์ของหัวข้อ

ฟิลด์ที่ไม่บังคับคัดลอกลิงก์ของหัวข้อ

ที่อยู่ที่แอปให้บริการคัดลอกลิงก์ของหัวข้อ

publisherคัดลอกลิงก์ของหัวข้อ

oauthคัดลอกลิงก์ของหัวข้อ

localesคัดลอกลิงก์ของหัวข้อ

แพลตฟอร์มใช้แต่ละฟิลด์อย่างไรในตอนนี้คัดลอกลิงก์ของหัวข้อ

แอป officialคัดลอกลิงก์ของหัวข้อ

ในหน้านี้