# 廣告 --- API 清單 - 共用[APP/WEB] - [廣告版位列表](#廣告版位列表) - 廣告管理[WEB] - [廣告商列表](#廣告商列表) - [廣告類別預設版位列表](#廣告類別預設版位列表) - [取得上傳網址](#取得上傳網址) - [廣告管理列表](#廣告管理列表) - [取得單一廣告管理明細](#取得單一廣告管理明細) - [新增廣告](#新增廣告) - [編輯廣告](#編輯廣告) - [編輯廣告下架日期](#編輯廣告下架日期) - [刪除廣告](#刪除廣告) - [取得廣告統計](#取得廣告統計) - 廣告[APP] - [廣告投放](#廣告投放) - [取得廣告明細](#取得廣告明細) - [廣告點擊](#廣告點擊) - [廣告觸及](#廣告觸及) - [取得會員專屬廣告列表](#取得會員專屬廣告列表) --- ## 廣告版位列表 ```url GET /ads/positions ``` #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- ```javascript ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 版位id, <br/>MY_MEMBER_ONLY:我的-會員專屬<br/>MY_HEALTH_EDU:我的-防疫衛教<br/>MY_HEALTH_ANALYSIS:我的-健康分析<br/>MY_CONSULT:我的-諮詢回覆<br/>MY_REWARD:我的-點收記錄<br/>HEALTH_MEASURE:健康-量測分析<br/>HEALTH_SPORT:健康-運動分析<br/>HEALTH_DIET:健康-飲食分析<br/>HEALTH_REPORT:健康-健康報告<br/>HEALTH_TREND:健康-健康趨勢<br/>HEALTH_WOUND:健康-傷口記錄 description | string | 版位名稱(說明) ```javascript { "httpCode": 200, "result": { "data": [ { "description": "我的-會員專屬", "id": "MY_MEMBER_ONLY" }, { "description": "我的-防疫衛教", "id": "MY_HEALTH_EDU" }, ... ] } } ``` ## 廣告商列表 ```url GET /ads-mgmt/ad-tenant-list ``` #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- ```javascript ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告商租戶id name | string | 廣告商租戶名稱 tenantType | string | 租戶類別, DEALER: 經銷單位, HOSPITAL:醫療機構, WMT:緯創醫學, BUSINESS:企業客戶, AD:廣告商 industryTypeList | string array | 租戶業別列表, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 ```javascript { "httpCode": 200, "result": { "data": [ { "id": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "name": "賣廣告的", "tenantType": "AD", "industryTypeList": [ "GYM", "HEALTH_SUPPLEMENT" ] }, { "id": "71466c25-e4a5-46df-bdb0-46ed44fcd5cc", "name": "opo2", "tenantType": "BUSINESS", "industryTypeList": [ "OTHER" ] }, ... ] } } ``` ## 廣告類別預設版位列表 ```url GET /ads-mgmt/category-positions ``` #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- ```javascript ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- category | string | 廣告類別, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 positions | string array | 版位id列表, ```javascript { "httpCode": 200, "result": { "data": [ { "positions": [ "MY_HEALTH_EDU", "MY_HEALTH_ANALYSIS", "HEALTH_MEASURE", "HEALTH_REPORT", "HEALTH_TREND" ], "category": "HEALTH_CHECK_CENTER" }, ... ] } } ``` ## 取得上傳網址 ```url POST /ads-mgmt/get-upload-url ``` * 新增/編輯廣告時用來上傳縮圖, 廣告圖/影片, 廣告檔案(PDF) #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- isMultipart | boolean | Y | false | 是否使用分段上傳 isThumbnail | boolean | Y | false | 上傳的是否為縮圖 fileName | String | Y | | 檔名，不包含副檔名，限制最多50字 fileType | String | Y | | 副檔名, 限制最多10字 totalPart | int | **N** (isMultipart=false)<br>**Y** (isMultipart=true) | | 總分塊數量，不可小於2 parts | Array [...part] | **N** (isMultipart=false)<br>**Y** (isMultipart=true) | | part 資訊 * part(Object) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- chunkSize | int | Y | | 該 chunk 的大小, bytes md5 | string | Y | | 該 part 的 md5 part | int | Y | | part number, 第幾塊 chunk ```javascript // 單檔 { "isMultipart": false, "isThumbnail": false, "fileName": "ad_bg_jp", "fileType": "png" } // 分塊上傳 { "isMultipart": true, "isThumbnail": false, "fileName": "giphy (7)", "fileType": "mp4", "totalPart": 2, "parts": [ { "chunkSize": 5242880, "md5": "5AACA89868CD486D81192221CF9F9415", "part": 1 }, { "chunkSize": 3145728, "md5": "5AACA89868CD486D81192221CF9F9415", "part": 2 } ] } ``` #### Response * data 欄位 | 型態 | 說明 --- | --- | --- objectKey | string | storage 中的 objectKey, **unique** uploadId | string | 識別該次上傳的 uploadId fileName | string | 名稱 fileType | string | 副檔名 url | string | 單檔上傳的時候，才會回傳該 url, 時效 3600 秒 parts | [...part] | multipart上傳各part的url * part(Object) 欄位 | 型態 | 說明 --- | --- | --- chunkSize | int | 該 chunk 的大小, bytes md5 | string | 該 part 的 md5 part | int | part number, 第幾塊 chunk url | string | 可上傳的 url, 時效 3600 秒 ```javascript // HttpStatus:422, 上傳的檔案類型不允許 { "errorMsg": "SERVICE_ERROR.ADS_MGMT_UPLOAD_FILE_TYPE_NOT_ALLOWED", "httpCode": 422 } // HttpStatus: 200 // 單檔 { "httpCode": 200, "result": { "data": { "objectKey": "ads/9f9de11b-12b9-4964-bae8-3233e9da065b.png", "uploadId": "11becd09-7571-4b0d-b8ee-cb3f09f66cf0", "fileName": "ad_bg_jp", "fileType": "png", // 單檔 才有 url "url": "http://192.168.100.239:12345/v1/AUTH_test/kmuh/ads%2F9f9de11b-12b9-4964-bae8-3233e9da065b.png?temp_url_sig=e61d9e721d860294bde4d0151e111ebf8ed57ed7&temp_url_expires=1554114780" } } } // 分塊上傳 { "httpCode": 200, "result": { "data": { "objectKey": "ads/f76adf26-1e22-4b18-980d-b9a68efc5171.mp4", "uploadId": "53fde368-43d9-455f-a610-62091fc30be6", "fileName": "giphy (7)", "fileType": "mp4", "parts": [ { "chunkSize": 5242880, "md5": "5AACA89868CD486D81192221CF9F9415", "part": 1, "url": "http://192.168.100.239:12345/v1/AUTH_test/kmuh_segments/ads%2Ff76adf26-1e22-4b18-980d-b9a68efc5171.mp4%2F1?temp_url_sig=796c52b00f75b62be658533b2fadbc7f14381e36&temp_url_expires=1554263771" }, { "chunkSize": 3145728, "md5": "5AACA89868CD486D81192221CF9F9415", "part": 2, "url": "http://192.168.100.239:12345/v1/AUTH_test/kmuh_segments/ads%2Ff76adf26-1e22-4b18-980d-b9a68efc5171.mp4%2F2?temp_url_sig=ad71de81dfbcd94bce4a091f2630c6f1373ff3cd&temp_url_expires=1554263771" } ] } } } ``` ## 廣告管理列表 ```url POST /ads-mgmt/list ``` #### Request * query(查詢條件json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- onDateStart | string | | | 上架日期查詢起日, 格式為YYYY-MM-DD onDateEnd | string | | | 上架日期查詢迄日, 格式為YYYY-MM-DD industryType | string | | | 廣告商業別, 若查詢全部請帶入空字串"", HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 status | string | | | 廣告上架狀態, 若查詢全部請帶入空字串"", NONE:未上架, ON:上架中, OFF:已下架 paymentStatus | string | | | 付費狀態, 若查詢全部請帶入空字串"", NONE:不需計費, UNPAID:未付費, PAID:已付費 name | string | | | 關鍵字, 查詢廣告標題或廣告商名稱 positions | string array | | | 廣告版位id列表, 若查詢全部請帶入空陣列[] * pagination(分頁json) 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- current | int | | 1 | 當前頁數 pageSize | int | | 10 | 每頁結果數量，-1 為顯示所有 * sorter(排序json), 預設是用更新時間降序排列 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- field | string | | updateTime | 排序欄位,可排序欄位有updateTime, tenantName, onDate, offDate, paymentStatus, status order | string | | desc | 生序或降序 ```javascript { "query": { "onDateStart": null, "onDateEnd": null, "industryType": "", "status": null, "paymentStatus": null, "name": null, "positions":[ "HEALTH_MEASURE", "MY_REWARD" ] }, "pagination": { "current": 1, "pageSize": 10 }, "sorter": { "field": "updateTime", "order": "desc" } } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id tenantId | string | 廣告商租戶id tenantName | string | 廣告商租戶名稱 title | string | 廣告標題 adType | string | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | storage中的縮圖objectKey objectKey | string | adType為FILE或IMAGE時, 表示storage 中的 objectKey, adType為URL時, 表示連結的網址 contentType | string | MineType 格式 content | string | adType為CONTENT時所填入的文字內容 onDate | Date | 上架日期 offDate | Date | 下架日期 exposureLevel | string | 曝光等級, NORMAL:一般, HIGH:高 paymentStatus | string | 付費狀況, NONE:不需計費, UNPAID:未付費, PAID:已付費 status | string | 上架狀態, NONE:未上架, ON:上架中, OFF:已下架 thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 url | string | adType為FILE或IMAGE時,可 download 的 url, 時效 3600 秒, adType為URL時, 表示連結的網址 industryTypeList | json array | 廣告商租戶的業別列表, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 categoryList | json array | 廣告類別列表, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 positionList | string array | 廣告版位列表 createTime | int | 建立時間 updateTime | int | 最後更新時間 * json of industryTypeList/categoryList 欄位 | 型態 | 說明 --- | --- | --- category | string | 廣告/業別 id description | string | 廣告/業別名稱(說明) ```javascript { "httpCode": 200, "result": { "data": [ { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "tenantName": "賣廣告的", "title": "TEST-AD-2", "adType": "URL", "thumbnailObjectKey": "abcd", "objectKey": "https://www.google.com", "onDate": 1630425600000, "offDate": 1635609600000, "exposureLevel": "NORMAL", "paymentStatus": "UNPAID", "status": "NONE", "thumbnailUrl": null, "url": null, "industryTypeList": [ { "category": "GYM", "description": "健身房" }, { "category": "HEALTH_SUPPLEMENT", "description": "保健品業者" } ], "categoryList": [ { "category": "GYM", "description": "健身房" }, { "category": "HEALTH_SUPPLEMENT", "description": "保健品業者" } ], "positionList": [ "HEALTH_MEASURE", "MY_REWARD" ] } ], "pagination": { "current": 1, "pageSize": 10, "total": 1 }, "sorter": { "field": "updateTime", "order": "desc" }, "total": 1 } } ``` ## 取得單一廣告管理明細 ```url POST /ads-mgmt/info ``` #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 廣告id ```javascript { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2" } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id tenantId | string | 廣告商租戶id tenantName | string | 廣告商租戶名稱 title | string | 廣告標題 adType | string | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | storage中的縮圖objectKey objectKey | string | adType為FILE或IMAGE時, 表示storage 中的 objectKey, adType為URL時, 表示連結的網址 contentType | string | MineType 格式 content | string | adType為CONTENT時所填入的文字內容 onDate | Date | 上架日期 offDate | Date | 下架日期 exposureLevel | string | 曝光等級, NORMAL:一般, HIGH:高 paymentStatus | string | 付費狀況, NONE:不需計費, UNPAID:未付費, PAID:已付費 status | string | 上架狀態, NONE:未上架, ON:上架中, OFF:已下架 thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 url | string | adType為FILE或IMAGE時,可 download 的 url, 時效 3600 秒, adType為URL時, 表示連結的網址 industryTypeList | json array | 廣告商租戶的業別列表, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 categoryList | json array | 廣告類別列表, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 positionList | string array | 廣告版位列表 createTime | int | 建立時間 updateTime | int | 最後更新時間 * json of industryTypeList/categoryList 欄位 | 型態 | 說明 --- | --- | --- category | string | 廣告/業別 id description | string | 廣告/業別名稱(說明) ```javascript // HttpStatus:400, 資料不存在 { "errorMsg": "API_ERROR.NOT_EXIST", "httpCode": 400 } // HttpStatus:200 { "httpCode": 200, "result": { "data": { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "tenantName": "賣廣告的", "title": "TEST-AD-2", "adType": "URL", "thumbnailObjectKey": "abcd", "objectKey": "https://www.google.com", "onDate": 1630425600000, "offDate": 1635609600000, "exposureLevel": "NORMAL", "paymentStatus": "UNPAID", "status": "NONE", "thumbnailUrl": null, "url": "https://www.google.com", "industryTypeList": [ { "category": "GYM", "description": "健身房" }, { "category": "HEALTH_SUPPLEMENT", "description": "保健品業者" } ], "categoryList": [ { "category": "GYM", "description": "健身房" }, { "category": "HEALTH_SUPPLEMENT", "description": "保健品業者" } ], "positionList": [ "HEALTH_MEASURE", "HEALTH_SPORT", "MY_HEALTH_EDU", "MY_REWARD" ] } } } ``` ## 新增廣告 ```url POST /ads-mgmt/add ``` #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | Y | | 廣告商租戶id title | string | Y | | 廣告標題, 限制最多30字 adType | string | Y | | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | Y | | 縮圖objectKey, 先取得縮圖上傳網址並上傳成功，取其 objectKey。 objectKey | string | **Y**(adType= URL/FILE/IMAGE) | | 若adType為FILE/IMAGE, 先取得上傳網址並上傳成功，取其 objectKey。若adType為URL則直接存放URL網址 contentType | string | | | MineType content | string | **Y**(adType=CONTENT) | | adType為CONTENT時所填入的文字內容, 限制最多500字 onDate | string | | | 上架日期, 日期格式為YYYY-MM-DD offDate | string | | | 下架日期, 日期格式為YYYY-MM-DD exposureLevel | string | Y | | 曝光等級, NORMAL:一般, HIGH:高 paymentStatus | string | Y | | 付費狀況, NONE:不需計費, UNPAID:未付費, PAID:已付費 categoryList | string array | Y | | 廣告類別列表, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 positionList | string array | Y | | 廣告版位列表 isMultipart | boolean | N | | adType=FILE/IMAGE時, 上傳的檔案是否分塊上傳，預設為 false totalPart | int | **N** (isMultipart=false)<br>**Y** (isMultipart=true) | | 總分塊數量，不可小於2 uploadId | string | **N** (isMultipart=false)<br>**Y** (isMultipart=true) | | 從 /ads-mgmt/get-upload-url 取得的 uploadId isThumbnailMultipart | boolean | N | | 縮圖上傳時是否分塊上傳，預設為 false thumbnailTotalPart | int | **N** (isThumbnailMultipart=false)<br>**Y** (isThumbnailMultipart=true) | | 縮圖上傳的總分塊數量，不可小於2 thumbnailUploadId | string | **N** (isThumbnailMultipart=false)<br>**Y** (isThumbnailMultipart=true) | | 從 /ads-mgmt/get-upload-url 取得的 uploadId ```javascript { "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "title": "TEST-AD-1", "adType": "URL", "thumbnailObjectKey": "ads/thumbnail/1edd53d8-329b-49f3-bd36-8dc89bfad05c.jpg", "objectKey": "https://www.google.com", "contentType": null, "content": null, "onDate": "2021-08-28", "offDate": null, "exposureLevel": "NORMAL", "paymentStatus": "NONE", "categoryList": [ "GYM", "HEALTH_SUPPLEMENT" ], "positionList": [ "MY_MEMBER_ONLY", "MY_HEALTH_EDU", "MY_HEALTH_ANALYSIS", "MY_REWARD", "HEALTH_MEASURE", "HEALTH_SPORT", "HEALTH_REPORT", "HEALTH_TREND" ], "isMultipart": false, "totalPart": null, "uploadId": null, "isThumbnailMultipart": false, "thumbnailTotalPart": null, "thumbnailUploadId": null } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id tenantId | string | 廣告商租戶id title | string | 廣告標題 adType | string | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | storage中的縮圖objectKey objectKey | string | adType為FILE或IMAGE時, 表示storage 中的 objectKey, adType為URL時, 表示連結的網址 contentType | string | MineType 格式 content | string | adType為CONTENT時所填入的文字內容 onDate | Date | 上架日期 offDate | Date | 下架日期 exposureLevel | string | 曝光等級, NORMAL:一般, HIGH:高 paymentStatus | string | 付費狀況, NONE:不需計費, UNPAID:未付費, PAID:已付費 status | string | 上架狀態, NONE:未上架, ON:上架中, OFF:已下架 createTime | int | 建立時間 updateTime | int | 最後更新時間 ```javascript { "httpCode": 200, "result": { "data": { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "title": "TEST-AD-1", "adType": "URL", "thumbnailObjectKey": "abcd", "objectKey": "https://www.google.com", "onDate": 1630425600000, "exposureLevel": "NORMAL", "paymentStatus": "NONE", "status": "NONE", "createTime": 1630549208878, "updateTime": 1630549208878, "creator": "a1131b35-dab0-4593-899b-9485356e02d4" } } } ``` ## 編輯廣告 ```url POST /ads-mgmt/update ``` #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 廣告id tenantId | string | Y | | 廣告商租戶id title | string | Y | | 廣告標題, 限制最多30字 adType | string | Y | | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | Y | | 縮圖objectKey, 先取得縮圖上傳網址並上傳成功，取其 objectKey。 objectKey | string | **Y**(adType= URL/FILE/IMAGE) | | 若adType為FILE/IMAGE, 先取得上傳網址並上傳成功，取其 objectKey。若adType為URL則直接存放URL網址 contentType | string | | | MineType content | string | **Y**(adType=CONTENT) | | adType為CONTENT時所填入的文字內容, 限制最多500字 onDate | string | | | 上架日期, 日期格式為YYYY-MM-DD offDate | string | | | 下架日期, 日期格式為YYYY-MM-DD exposureLevel | string | Y | | 曝光等級, NORMAL:一般, HIGH:高 paymentStatus | string | Y | | 付費狀況, NONE:不需計費, UNPAID:未付費, PAID:已付費 categoryList | string array | Y | | 廣告類別列表, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 positionList | string array | Y | | 廣告版位列表 isMultipart | boolean | N | | adType=FILE/IMAGE時, 上傳的檔案是否分塊上傳，預設為 false totalPart | int | **N** (isMultipart=false)<br>**Y** (isMultipart=true) | | 總分塊數量，不可小於2 uploadId | string | **N** (isMultipart=false)<br>**Y** (isMultipart=true) | | 從 /ads-mgmt/get-upload-url 取得的 uploadId isThumbnailMultipart | boolean | N | | 縮圖上傳時是否分塊上傳，預設為 false thumbnailTotalPart | int | **N** (isThumbnailMultipart=false)<br>**Y** (isThumbnailMultipart=true) | | 縮圖上傳的總分塊數量，不可小於2 thumbnailUploadId | string | **N** (isThumbnailMultipart=false)<br>**Y** (isThumbnailMultipart=true) | | 從 /ads-mgmt/get-upload-url 取得的 uploadId ```javascript { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "title": "TEST-AD-1", "adType": "URL", "thumbnailObjectKey": "ads/thumbnail/1edd53d8-329b-49f3-bd36-8dc89bfad05c.jpg", "objectKey": "https://www.google.com", "contentType": null, "content": null, "onDate": "2021-08-28", "offDate": null, "exposureLevel": "NORMAL", "paymentStatus": "NONE", "categoryList": [ "GYM", "HEALTH_SUPPLEMENT" ], "positionList": [ "MY_MEMBER_ONLY", "MY_HEALTH_EDU", "MY_HEALTH_ANALYSIS", "MY_REWARD", "HEALTH_MEASURE", "HEALTH_SPORT", "HEALTH_REPORT", "HEALTH_TREND" ], "isMultipart": false, "totalPart": null, "uploadId": null, "isThumbnailMultipart": false, "thumbnailTotalPart": null, "thumbnailUploadId": null } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id tenantId | string | 廣告商租戶id title | string | 廣告標題 adType | string | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | storage中的縮圖objectKey objectKey | string | adType為FILE或IMAGE時, 表示storage 中的 objectKey, adType為URL時, 表示連結的網址 contentType | string | MineType 格式 content | string | adType為CONTENT時所填入的文字內容 onDate | Date | 上架日期 offDate | Date | 下架日期 exposureLevel | string | 曝光等級, NORMAL:一般, HIGH:高 paymentStatus | string | 付費狀況, NONE:不需計費, UNPAID:未付費, PAID:已付費 status | string | 上架狀態, NONE:未上架, ON:上架中, OFF:已下架 createTime | int | 建立時間 updateTime | int | 最後更新時間 ```javascript // HttpStatus:400, 資料不存在 { "errorMsg": "API_ERROR.NOT_EXIST", "httpCode": 400 } // HttpStatus:422, 不允許編輯已下架的廣告 { "errorMsg": "SERVICE_ERROR.ADS_MGMT_UPDATE_OFF_AD_NOT_ALLOWED", "httpCode": 422 } // HttpStatus:200 { "httpCode": 200, "result": { "data": { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "title": "TEST-AD-1", "adType": "URL", "thumbnailObjectKey": "abcd", "objectKey": "https://www.google.com", "onDate": 1630425600000, "exposureLevel": "NORMAL", "paymentStatus": "NONE", "status": "NONE", "createTime": 1630549208878, "updateTime": 1630549208878, "creator": "a1131b35-dab0-4593-899b-9485356e02d4" } } } ``` ## 編輯廣告下架日期 ```url POST /ads-mgmt/update-off ``` #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 廣告id offDate | string | | | 下架日期, 日期格式為YYYY-MM-DD ```javascript { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "offDate": "2021-10-30" } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id tenantId | string | 廣告商租戶id title | string | 廣告標題 adType | string | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | storage中的縮圖objectKey objectKey | string | adType為FILE或IMAGE時, 表示storage 中的 objectKey, adType為URL時, 表示連結的網址 contentType | string | MineType 格式 content | string | adType為CONTENT時所填入的文字內容 onDate | Date | 上架日期 offDate | Date | 下架日期 exposureLevel | string | 曝光等級, NORMAL:一般, HIGH:高 paymentStatus | string | 付費狀況, NONE:不需計費, UNPAID:未付費, PAID:已付費 status | string | 上架狀態, NONE:未上架, ON:上架中, OFF:已下架 createTime | int | 建立時間 updateTime | int | 最後更新時間 ```javascript // HttpStatus:400, 資料不存在 { "errorMsg": "API_ERROR.NOT_EXIST", "httpCode": 400 } // HttpStatus:422, 不允許編輯已下架的廣告 { "errorMsg": "SERVICE_ERROR.ADS_MGMT_UPDATE_OFF_AD_NOT_ALLOWED", "httpCode": 422 } // HttpStatus:200 { "httpCode": 200, "result": { "data": { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "title": "TEST-AD-1", "adType": "URL", "thumbnailObjectKey": "abcd", "objectKey": "https://www.google.com", "onDate": 1630425600000, "exposureLevel": "NORMAL", "paymentStatus": "NONE", "status": "NONE", "createTime": 1630549208878, "updateTime": 1630549208878, "creator": "a1131b35-dab0-4593-899b-9485356e02d4" } } } ``` ## 刪除廣告 ```url POST /ads-mgmt/delete ``` #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 廣告id ```javascript { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2" } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- count | int | 刪除筆數, > 0 表示成功刪除 ```javascript // HttpStatus:400, 資料不存在 { "errorMsg": "API_ERROR.NOT_EXIST", "httpCode": 400 } // HttpStatus:422, 不允許刪除廣告(上架中, 已下架) { "errorMsg": "SERVICE_ERROR.ADS_MGMT_DELETE_AD_NOT_ALLOWED", "httpCode": 422 } // HttpStatus:200 { "httpCode": 200, "result": { "data": { "count": 1 } } } ``` ## 取得廣告統計 ```url POST /ads-mgmt/ad/statistics ``` #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- adId | string | Y | | 廣告id position | string | | | 廣告版位 ```javascript { "adId": "ddb19c99-dd16-46b9-883e-92446070761b", "position": "MY_MEMBER_ONLY" } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- adInfo | json | 廣告info json reachInfo | json | 廣告曝光分析json clickInfo | json | 廣告點擊分析json * adInfo (廣告info json) 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id tenantId | string | 廣告商租戶id tenantName | string | 廣告商租戶名稱 title | string | 廣告標題 adType | string | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | storage中的縮圖objectKey objectKey | string | adType為FILE或IMAGE時, 表示storage 中的 objectKey, adType為URL時, 表示連結的網址 contentType | string | MineType 格式 content | string | adType為CONTENT時所填入的文字內容 onDate | Date | 上架日期 offDate | Date | 下架日期 exposureLevel | string | 曝光等級, NORMAL:一般, HIGH:高 paymentStatus | string | 付費狀況, NONE:不需計費, UNPAID:未付費, PAID:已付費 status | string | 上架狀態, NONE:未上架, ON:上架中, OFF:已下架 thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 url | string | adType為FILE或IMAGE時,可 download 的 url, 時效 3600 秒, adType為URL時, 表示連結的網址 industryTypeList | json array | 廣告商租戶的業別列表, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 categoryList | json array | 廣告類別列表, HEALTH_CHECK_CENTER:健檢中心, GYM:健身房, CLINIC:診所, REGIONAL_HOSPITAL:區域醫院, MEDICAL_CENTER:醫學中心, HEALTH_SUPPLEMENT:保健品業者, MEDICAL_DEVICE:醫療器材業者, CATERING:餐飲業者, CONSUMABLES:耗材業者, OTHER:其他 positionList | string array | 廣告版位列表 createTime | int | 建立時間 updateTime | int | 最後更新時間 * json of industryTypeList/categoryList 欄位 | 型態 | 說明 --- | --- | --- category | string | 廣告/業別 id description | string | 廣告/業別名稱(說明) * reachInfo (活動曝光分析json) 欄位 | 型態 | 說明 --- | --- | --- totalCount | int | 總曝光人數 totalTimes | int | 總曝光人次 totalMaleCount | int | 總男性曝光人數 totalFemaleCount | int | 總女性曝光人數 totalMaleTimes | int | 總男性曝光人次 totalFemaleTimes | int | 總女性曝光人次 totalMaleCountRate | double | 總男性人數佔比 totalFemaleCountRate | double | 總女性人數佔比 totalMaleTimesRate | double | 總男性人次佔比 totalFemaleTimesRate | double | 總女性人次佔比 details | json array | 年齡統計 json array * clickInfo (活動點擊分析json) 欄位 | 型態 | 說明 --- | --- | --- totalCount | int | 總點擊人數 totalTimes | int | 總點擊人次 totalMaleCount | int | 總男性點擊人數 totalFemaleCount | int | 總女性點擊人數 totalMaleTimes | int | 總男性點擊人次 totalFemaleTimes | int | 總女性點擊人次 totalMaleCountRate | double | 總男性人數佔比 totalFemaleCountRate | double | 總女性人數佔比 totalMaleTimesRate | double | 總男性人次佔比 totalFemaleTimesRate | double | 總女性人次佔比 clickRate | double | 點擊率, 點擊率 = 點擊人數/曝光人數 details | json array | 年齡統計 json array * details (json array of reachInfo, clickInfo, registerInfo, signInInfo) 欄位 | 型態 | 說明 --- | --- | --- ageLevel | string | 年齡level label | string | 年齡區間顯示(標X軸) maleCount | int | 男性人數 femaleCount | int | 女性人數 maleTimes | int | 男性人次 femaleTimes | int | 女性人次 ```javascript { "httpCode": 200, "result": { "data": { "adInfo": { "id": "ddb19c99-dd16-46b9-883e-92446070761b", "tenantId": "858b7fbb-3ba0-4d49-9882-c893a1ef07dc", "tenantName": "緯緯醫學", "title": "no會員", "adType": "CONTENT", "thumbnailObjectKey": "ads/5ce7968b-f7ad-41cd-ab40-6ca139859062.jpg", "objectKey": "ads/5ce7968b-f7ad-41cd-ab40-6ca139859062.jpg", "content": "除了會員 全都有", "onDate": 1630425600000, "offDate": 1633017600000, "exposureLevel": "NORMAL", "paymentStatus": "NONE", "status": "OFF", "createTime": 1631004064206, "updateTime": 1633109400068, "thumbnailUrl": "http://10.31.104.23/swift/v1/AUTH_test/kmuh/ads/5ce7968b-f7ad-41cd-ab40-6ca139859062.jpg?temp_url_sig=c961a97edc05d156c07caed44dd59d9429bf8771&temp_url_expires=1655375956", "url": null, "industryTypeList": [ { "category": "OTHER", "description": "其他" } ], "positionList": [ "HEALTH_MEASURE", "HEALTH_REPORT", "HEALTH_SPORT", "HEALTH_TREND", "MY_CONSULT", "MY_HEALTH_ANALYSIS", "MY_HEALTH_EDU", "MY_REWARD" ], "categoryList": [ { "category": "CLINIC", "description": "診所" }, { "category": "GYM", "description": "健身房" }, { "category": "HEALTH_CHECK_CENTER", "description": "健檢中心" }, { "category": "HEALTH_SUPPLEMENT", "description": "保健品業者" }, { "category": "MEDICAL_CENTER", "description": "醫學中心" }, { "category": "MEDICAL_DEVICE", "description": "醫療器材業者" }, { "category": "REGIONAL_HOSPITAL", "description": "區域醫院" } ] }, "reachInfo": { "totalCount": 2, "totalTimes": 687, "totalMaleCount": 2, "totalFemaleCount": 0, "totalMaleTimes": 687, "totalFemaleTimes": 0, "totalMaleCountRate": 100.0, "totalFemaleCountRate": 0.0, "totalMaleTimesRate": 100.0, "totalFemaleTimesRate": 0.0, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 1, "femaleCount": 0, "maleTimes": 100, "femaleTimes": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 1, "femaleCount": 0, "maleTimes": 587, "femaleTimes": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 } ] }, "clickInfo": { "totalCount": 1, "totalTimes": 97, "totalMaleCount": 1, "totalFemaleCount": 0, "totalMaleTimes": 97, "totalFemaleTimes": 0, "totalMaleCountRate": 100.0, "totalFemaleCountRate": 0.0, "totalMaleTimesRate": 100.0, "totalFemaleTimesRate": 0.0, "clickRate": 50.0, "details": [ { "ageLevel": "level1", "label": "30歲以下", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level2", "label": "30-39歲", "maleCount": 1, "femaleCount": 0, "maleTimes": 97, "femaleTimes": 0 }, { "ageLevel": "level3", "label": "40-49歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level4", "label": "50-59歲", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 }, { "ageLevel": "level5", "label": "60歲以上", "maleCount": 0, "femaleCount": 0, "maleTimes": 0, "femaleTimes": 0 } ] } } } } ``` ## 廣告投放 ```url POST /ad/push ``` * 此API會將取得的廣告算入觸及, 所以不需要call /ad/reach API #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | | | 租戶id, 若不帶入, 則會由userToken帶入 position | string | Y | | 廣告版位id ```javascript { "tenantId": "7daf1fc2-e7e6-4642-90a8-ff11f0febbe2", "position": "MY_HEALTH_EDU" } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id tenantName | string | 廣告商租戶名稱 title | string | 廣告標題 adType | string | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | storage中的縮圖objectKey objectKey | string | adType為FILE或IMAGE時, 表示storage 中的 objectKey, adType為URL時, 表示連結的網址 thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 url | string | adType為FILE或IMAGE時,可 download 的 url, 時效 3600 秒, adType為URL時, 表示連結的網址 ```javascript { "httpCode": 200, "result": { "data": { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "tenantName": "賣廣告的", "title": "TEST-AD-2", "adType": "URL", "thumbnailObjectKey": "abcd", "objectKey": "https://www.google.com", "thumbnailUrl": "http://192.168.101.120/swift/v1/AUTH_test/kmuh/abcd?temp_url_sig=157c26821ed477e5c63bf2d254c424cdeca1d890&temp_url_expires=1631005142", "url": "https://www.google.com" } } } ``` ## 取得廣告明細 ```url POST /ad/info ``` * adType若為CONTENT, 會需要call此API,取得內容明細 * 此API已包含廣告點擊, 不需再call /ad/click API #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 廣告id position | string | Y | | 廣告版位id ```javascript { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "position": "MY_HEALTH_EDU" } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id tenantName | string | 廣告商租戶名稱 title | string | 廣告標題 adType | string | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | storage中的縮圖objectKey objectKey | string | adType為FILE或IMAGE時, 表示storage 中的 objectKey, adType為URL時, 表示連結的網址 contentType | string | MineType 格式 content | string | adType為CONTENT時所填入的文字內容 thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 url | string | adType為FILE或IMAGE時,可 download 的 url, 時效 3600 秒, adType為URL時, 表示連結的網址 ```javascript // HttpStatus:400, 資料不存在 { "errorMsg": "API_ERROR.NOT_EXIST", "httpCode": 400 } // HttpStatus:200 { "httpCode": 200, "result": { "data": { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "tenantName": "賣廣告的", "title": "TEST-AD-2", "adType": "URL", "thumbnailObjectKey": "abcd", "objectKey": "https://www.google.com", "onDate": 1630425600000, "offDate": 1635609600000, "exposureLevel": "NORMAL", "paymentStatus": "UNPAID", "status": "NONE", "thumbnailUrl": "http://192.168.101.120/swift/v1/AUTH_test/kmuh/abcd?temp_url_sig=157c26821ed477e5c63bf2d254c424cdeca1d890&temp_url_expires=1631005142", "url": "https://www.google.com" } } } ``` ## 廣告點擊 ```url POST /ad/click ``` * adType若為URL/FILE/IMAGE時, 若不call /ad/info API而直接跳轉URL/下載檔案/開啟大圖時, 需先call 此API以計算廣告點擊 #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 廣告id position | string | Y | | 廣告版位id ```javascript { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "position": "MY_HEALTH_EDU" } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id ```javascript // HttpStatus:400, 資料不存在 { "errorMsg": "API_ERROR.NOT_EXIST", "httpCode": 400 } // HttpStatus:200 { "httpCode": 200, "result": { "data": { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2" } } } ``` ## 廣告觸及 ```url POST /ad/reach ``` * 此API為會員專屬廣告列表所用, 在會員廣告專屬列表時, 由APP控制在廣告呈現給使用者時, call此API計算廣告觸及 #### Request 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- id | string | Y | | 廣告id position | string | Y | | 廣告版位id ```javascript { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "position": "MY_HEALTH_EDU" } ``` #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id ```javascript // HttpStatus:400, 資料不存在 { "errorMsg": "API_ERROR.NOT_EXIST", "httpCode": 400 } // HttpStatus:200 { "httpCode": 200, "result": { "data": { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2" } } } ``` ## 取得會員專屬廣告列表 ```url GET /ad/member-only ``` * 此API的廣告列表不會算入觸及, 需要APP控制再call /ad/reach API #### QueryString of API 欄位 | 型態 | 必填 | 預設 | 說明 ---|---|---|---|--- tenantId | string | | | 租戶id, 在多租戶情況下,可指定某個租戶下的會員專屬廣告, 若不傳入此參數,會查詢此使用者所有租戶下的會員專屬廣告 #### Response 欄位 | 型態 | 說明 --- | --- | --- id | string | 廣告id tenantName | string | 廣告商租戶名稱 title | string | 廣告標題 adType | string | 廣告類型, URL:連結, FILE:檔案, IMAGE:圖片, CONTENT:文字內容 thumbnailObjectKey | string | storage中的縮圖objectKey objectKey | string | adType為FILE或IMAGE時, 表示storage 中的 objectKey, adType為URL時, 表示連結的網址 thumbnailUrl | string | 可 download 的 縮圖url, 時效 3600 秒 url | string | adType為FILE或IMAGE時,可 download 的 url, 時效 3600 秒, adType為URL時, 表示連結的網址 ```javascript { "httpCode": 200, "result": { "data": [ { "id": "df2e6892-9ee2-4aab-9990-c5a62d618be2", "tenantName": "賣廣告的", "title": "TEST-AD-2", "adType": "URL", "thumbnailObjectKey": "abcd", "objectKey": "https://www.google.com", "thumbnailUrl": "http://192.168.101.120/swift/v1/AUTH_test/kmuh/abcd?temp_url_sig=157c26821ed477e5c63bf2d254c424cdeca1d890&temp_url_expires=1631005142", "url": "https://www.google.com" }, ... ] } } ```