1 files changed, 115 insertions, 0 deletions
diff --git a/files/zh-tw/webapi/simple_push/index.html b/files/zh-tw/webapi/simple_push/index.html
new file mode 100644
index 0000000000..da0015bd11
--- /dev/null
+++ b/files/zh-tw/webapi/simple_push/index.html
@@ -0,0 +1,115 @@
+---
+title: Simple Push API
+slug: WebAPI/Simple_Push
+translation_of: Archive/B2G_OS/API/Simple_Push_API
+---
+<p>{{ SeeCompatTable() }}</p>
+<p><a href="https://wiki.mozilla.org/WebAPI/SimplePush" title="https://wiki.mozilla.org/WebAPI/SimplePush">Simple Push API</a> 也是所謂的 Push Notification API，可在接收通知時喚醒 App。多個 App 可請求「共用其伺服器」的單一網址，以便傳送 App 的後續版本號碼。另外亦可作為同步化機制，從第三方伺服器取得最新資料。</p>
+<p>SimplePush API 可透過 push 屬性 (來自於 <a href="https://developer.mozilla.org/en-US/docs/Web/API/PushManager" title="/en-US/docs/Web/API/PushManager">PushManager</a> 專案) 而擴充 <a href="https://developer.mozilla.org/en-US/docs/Web/API/window.navigator" title="/en-US/docs/Web/API/window.navigator">window.navigator</a>，並添增新的事件給使用者，以監控推播 (Push) 的狀態。</p>
+<h2 id="範例">範例</h2>
+<p>在本範例中，我們將依照下列步驟而設定完整的推播：</p>
+<ol>
+ <li>將 <code>push</code> <code>的授權</code>新增至 manifest 檔案中</li>
+ <li>呼叫 <code>push.register()</code> 以請求終端 (Endpoint)</li>
+ <li>將終端傳送到自己的伺服器</li>
+ <li>針對 App 之內的推播通知，新增訊息處理器 (Message handler)</li>
+ <li>從自己的伺服器中送出通知</li>
+</ol>
+<h3 id="修改_manifest_檔案">修改 manifest 檔案</h3>
+<p>另外需修改 manifest 檔案中的 2 個地方：</p>
+<ol>
+ <li><a href="https://developer.mozilla.org/docs/Web/Apps/Manifest#messages" title="https://developer.mozilla.org/en-US/docs/Web/Apps/Manifest?redirectlocale=en-US&amp;redirectslug=Apps%2FManifest#messages">messages 欄位</a>：新增<code> push</code> 與 <code>push-register</code> 訊息。</li>
+ <li><a href="https://developer.mozilla.org/docs/Web/Apps/Manifest#permissions" title="https://developer.mozilla.org/en-US/docs/Web/Apps/Manifest?redirectlocale=en-US&amp;redirectslug=Apps%2FManifest#permissions">permissions 欄位</a>：新增想要接收推播通知的 App。</li>
+</ol>
+<pre><span class="s2">"messages"</span><span class="o">:</span> <span class="cp">[</span>
+   <span class="p">{</span> <span class="s2">"push"</span><span class="p">:</span> <span class="s2">"/index.html"</span><span class="p">},</span>
+   <span class="p">{</span> <span class="s2">"push-register"</span><span class="p">:</span> <span class="s2">"/index.html"</span><span class="p">}</span>
+<span class="cp">]</span><span class="o">,</span>
+<span class="s2">"permissions"</span><span class="o">:</span> <span class="p">{</span>
+  <span class="s2">"push"</span><span class="o">:</span> <span class="err">{
+    </span>"description": "Required for be updated with new goals in soccer matchs",<span class="err">
+</span><span class="p">  }</span>
+<span class="err">}</span></pre>
+<h3 id="呼叫_domxref(PushManager.register)_以請求終端">呼叫 {{domxref("PushManager.register")}} 以請求終端</h3>
+<p>一旦你認為該是請求終端的時候 (例如使用者登入，或有人想看場棒球賽的時候)，即可呼叫此程式碼。</p>
+<pre><span class="k">if</span> <span class="p">(</span><span class="nx">navigator</span><span class="p">.</span><span class="nx">push</span><span class="p">)</span> <span class="p">{</span>
+  <span class="kd">var</span> <span class="nx">req</span> <span class="o">=</span> <span class="nx">navigator</span><span class="p">.</span><span class="nx">push</span><span class="p">.</span><span class="nx">register</span><span class="p">();</span>
+
+  <span class="nx">req</span><span class="p">.</span><span class="brush: js">onsuccess</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span>
+    <span class="kd">var</span> <span class="nx">endpoint</span> <span class="o">=</span> <span class="nx">req</span><span class="p">.</span><span class="nx">result</span><span class="p">;</span>
+      <span class="nx">debug</span><span class="p">(</span><span class="s2">"New endpoint: "</span> <span class="o">+</span> <span class="nx">endpoint</span> <span class="p">);</span>
+    <span class="p">}</span>
+
+   <span class="nx">req</span><span class="p">.</span><span class="nx">onerror</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span>
+     <span class="nx">debug</span><span class="p">(</span><span class="s2">"Error getting a new endpoint: "</span> <span class="o">+</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">(</span><span class="nx">e</span><span class="p">));</span>
+   <span class="p">}</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+  <span class="c1">// No push on the DOM</span>
+<span class="p">}</span></pre>
+<h3 id="將終端傳送至自己的伺服器">將終端傳送至自己的伺服器</h3>
+<p>一旦獲得終端之後，就必須將之傳送至自己的 App 伺服器上。現有很多傳送終端的方法，如寄送電子郵件，或透過 <code>POST、</code><code>PUT、</code><code>GET</code><code> </code>均可傳送終端。我們建議以「來自於 App 的使用者資料」來儲存終端，例如 cookie、使用者名稱，或任何你用來識別終端使用者的資料均可。</p>
+<p>但如果你正把資料傳送到伺服器，我們還是建議下列要點：</p>
+<ol>
+ <li>以 XMLHttpRequest 傳送。</li>
+ <li>最好使用 HTTPS。如果某人中斷了你的終端，即可開始將通知傳送到自己的 App。</li>
+ <li>使用如 cookie 的機制，可比對使用者 (或 App 安裝作業) 與終端。</li>
+</ol>
+<h3 id="新增_push_訊息處理器">新增 <code>push</code> 訊息處理器</h3>
+<p>一旦設定終端完畢，就可讓 App 開始監聽推播訊息。此功能亦可註冊在主要的 <code>index.html</code> 檔案，或註冊在自己的 <code>main.js</code> 指令碼中；也能註冊在特殊的 <code>push-message.html</code> 檔案 (特殊之處在於該檔案之內僅有指令碼) 上。這功能之所以方便的原因在於：如果接收到 <code>push</code> 訊息且 App 處於關閉狀態時，則該 App 只會載入一小部分的 HTML/JavaScript 程式碼，而且你也可以決定是否要完全開啟 App，或在背景中執行某些作業即可。</p>
+<pre><span class="k">if</span> <span class="p">(</span><span class="nb">window</span><span class="p">.</span><span class="nx">navigator</span><span class="p">.</span><span class="nx">mozSetMessageHandler</span><span class="p">)</span> <span class="p">{</span>
+  <span class="nb">window</span><span class="p">.</span><span class="nx">navigator</span><span class="p">.</span><span class="nx">mozSetMessageHandler</span><span class="p">(</span><span class="s1">'push'</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span>
+    <span class="nx">debug</span><span class="p">(</span><span class="s1">'My endpoint is '</span> <span class="o">+</span> <span class="nx">e</span><span class="p">.</span><span class="nx">pushEndpoint</span><span class="p">);</span>
+    <span class="nx">debug</span><span class="p">(</span><span class="s1">'My new version is '</span> <span class="o">+</span>  <span class="nx">e</span><span class="p">.</span><span class="nx">version</span><span class="p">);</span>
+    <span class="c1">//Remember that you can handle here if you have more than</span>
+    <span class="c1">//one pushEndpoint</span>
+    <span class="k">if</span> <span class="p">(</span><span class="nx">e</span><span class="p">.</span><span class="nx">pushEndpoint</span> <span class="o">===</span> <span class="nx">emailEndpoint</span><span class="p">)</span> <span class="p">{</span>
+      <span class="nx">emailHandler</span><span class="p">(</span><span class="nx">e</span><span class="p">.</span><span class="nx">version</span><span class="p">);</span>
+    <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="nx">e</span><span class="p">.</span><span class="nx">pushEndpoint</span> <span class="o">===</span> <span class="nx">imEndpoint</span><span class="p">)</span> <span class="p">{</span>
+      <span class="nx">imHandler</span><span class="p">(</span><span class="nx">e</span><span class="p">.</span><span class="nx">version</span><span class="p">);</span>
+    <span class="p">}</span>
+  <span class="p">});</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+  <span class="c1">// No message handler</span>
+<span class="p">}</span></pre>
+<h3 id="新增_push-register_訊息處理器">新增 <code>push-register</code> 訊息處理器</h3>
+<div class="note">
+ <p>請確實添增此處理器，並檢查是否正常運作。只要在產生 <code>push-register </code>訊息當下，你並未重新註冊自己的終端，則之後將<strong>無法</strong>繼續接收其他推播通知。</p>
+</div>
+<p>一旦裝置變更了自己的 UAID (可能是因為推播伺服器變更，或當機之後需恢復作業，或其他更多情形)，就會將 <code>push-register</code> 訊息傳送至所有 App。也就是說，因為你之前的終端均已無效，所以你<strong>必須</strong>再次重新註冊所有的終端。</p>
+<pre><span class="k">if</span> <span class="p">(</span><span class="nb">window</span><span class="p">.</span><span class="nx">navigator</span><span class="p">.</span><span class="nx">mozSetMessageHandler</span><span class="p">)</span> <span class="p">{</span>
+  <span class="nb">window</span><span class="p">.</span><span class="nx">navigator</span><span class="p">.</span><span class="nx">mozSetMessageHandler</span><span class="p">(</span><span class="s1">'push-register'</span><span class="p">,</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span>
+    console.log<span class="p">(</span><span class="s1">'push-register received, I need to register my endpoint(s) again!'</span><span class="p">);</span>
+
+<span class="c1">    <span class="kd">var</span> <span class="nx">req</span> <span class="o">=</span> <span class="nx">navigator</span><span class="p">.</span><span class="nx">push</span><span class="p">.</span><span class="nx">register</span><span class="p">();</span>
+  <span class="nx">  req</span><span class="p">.</span><span class="brush: js">onsuccess</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span>
+    <span class="kd">  var</span> <span class="nx">endpoint</span> <span class="o">=</span> <span class="nx">req</span><span class="p">.</span><span class="nx">result</span><span class="p">;</span>
+      console.log<span class="p">(</span><span class="s2">"New endpoint: "</span> <span class="o">+</span> <span class="nx">endpoint</span> <span class="p">);
+      localStorage.endpoint = endpoint;</span>
+    <span class="p">}</span>
+
+   <span class="nx"> req</span><span class="p">.</span><span class="nx">onerror</span> <span class="o">=</span> <span class="kd">function</span><span class="p">(</span><span class="nx">e</span><span class="p">)</span> <span class="p">{</span>
+      console.error<span class="p">(</span><span class="s2">"Error getting a new endpoint: "</span> <span class="o">+</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">(</span><span class="nx">e</span><span class="p">));</span>
+   <span class="p"> }</span></span>
+  <span class="p">});</span>
+<span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+  <span class="c1">// No message handler</span>
+<span class="p">}</span></pre>
+<h3 id="傳送通知">傳送通知</h3>
+<p>一旦你的伺服器擁有 <code>endpoint</code> 之後，「傳送通知」就如同「將 <code>HTTP PUT</code> 的請求 (其內容具備 <code>version=&lt;version&gt;</code><code>) </code>傳送至終端」一樣簡單。先假想某個終端具備下列網址：</p>
+<p><code>https://push.src.openwebdevice.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef</code></p>
+<p>而且是版本 5：</p>
+<p><code>version=5</code></p>
+<p>搭配 curl：</p>
+<p><code>curl -X PUT -d "version=5" https://push.src.openwebdevice.com/v1/notify/abcdef01234567890abcdefabcdef01234567890abcdef</code></p>
+<p>如果伺服器正確運作，所取得的反應內容就會包含 <code>200 Status (OK)</code> 與 <code>{}</code> 各 1 組作為內容 (Body)。如果發生錯誤，則會送出有效的 JSON 以解釋該錯誤。</p>
+<p>另請注意，版號應該為逐漸遞增的整數。如果新版本的版號，小於裝置/伺服器上已儲存的版本，則 App <strong>不會</strong>獲得新的通知。</p>
+<h2 id="規格">規格</h2>
+<p>{{page("/en-US/docs/Web/API/PushManager","Specifications")}}</p>
+<h2 id="瀏覽器相容性">瀏覽器相容性</h2>
+<p>{{page("/en-US/docs/Web/API/PushManager","Browser_compatibility")}}</p>
+<h2 id="另可參閱">另可參閱</h2>
+<ul>
+ <li>{{domxref("PushManager")}}</li>
+ <li>{{domxref("window.navigator.push","navigator.push")}}</li>
+ <li><a href="https://github.com/frsela/pushJSlibrary" title="https://github.com/frsela/pushJSlibrary">pushJSLibrary, a push shim for browsers that do not implement the API</a></li>
+</ul>