Guides and Sample Code

Developer

Playground Book Format Reference

On This Page

Creating Subscriptions
サブスクリプションの作成

If you're writing episodic content in your Swift Playgrounds learning material, or want to space out the releases of your lessons over time, you can build a subscription that guides people through your lessons one by one. This chapter describes the process of creating and hosting the subscription data you need to start publishing your playgrounds so people can subscribe to them in Swift Playgrounds.
あなたがSwift Playgrounds学習素材の中で挿話的なコンテンツを書いている、または時間を置いてあなたのレッスンのリリースの間隔を空けたいならば、あなたはサブスクリプション(定期購読、配信)を構築して、人々にあなたのレッスンを1つずつ案内できます。この章は、あなたの幾つかのプレイグラウンドの出版を開始して人々がそれらをSwift Playgroundsの中で購読(受信)できるようにするため、あなたが必要とするサブスクリプションデータを作成およびホストする過程を解説します。

Understanding Subscriptions
サブスクリプションを理解する

Swift Playgrounds subscriptions live on the Internet as feeds. Like podcasts, subscriptions in Swift Playgrounds are a sequence of episodic content learners go through in an order that builds knowledge, though some parts may be skippable depending on the learner.
Swift Playgroundsサブスクリプションは、インターネット上にフィードとして置かれます。ポッドキャストのように、Swift Playgroundsの中のサブスクリプションは学習者がある順序で終了する一連の散発的なコンテンツで、理解を深めるためのものですが、幾つかの部分は学習者によっては省略できます。

A feed is a downloadable list of items that apps and websites understand. The feed for your subscription is a way for you publish a set of playgrounds that the Swift Playgrounds app knows how to download, process, and display. Feeds in Swift Playgrounds are structured in a text format called JSON.
あるフィードは、あるダウンロード可能な幾つかの項目のリストで、アプリとウェブサイトが理解できるものです。あなたのサブスクリプションのためのフィードは、Swift Playgroundsアプリがダウンロード、処理、そして表示する方法を知っている一揃いのプレイグラウンドをあなたが出版するための1つの方法です。Swift Playgroundsにおけるフィードは、JSONと呼ばれるテキスト形式の構造をもちます。

Understanding Feeds and JSON
フィードとJSONを理解する

JSON is a textual data format that many apps and websites use to communicate and share information. It consists primarily of lists, definition lists, and raw values like strings and numbers. You use it to build up a feed for your subscription.
JSONは、多くのアプリとウェブサイトが情報を伝達および共有するために使うテキストデータ書式です。それは主として幾つかのリスト、定義リスト、そして文字列や数値のような生の値から成ります。あなたはそれを使って、あなたのサブスクリプションのためのフィードを作り上げます。

A simple—yet complete—JSON document looks like this:
ある単純な—未完成の—JSON文書はこのように見えます:

  1. {
  2. "bookTitle": "Whimsical Swift Syntax",
  3. "publishDate": 2017,
  4. "simpleList": ["one", 1, "two", 2]
  5. }

The example document isn't detailed enough to be a real feed for a playground subscription, but it illustrates the kind of information a feed contains. The JSON you'll see used by apps is typically longer, but those longer JSON documents follow the same rules of quoting and nesting. For more information about JSON, see ECMA-404: The JSON Data Interchange Format.
この例の文書は、プレイグラウンドサブスクリプションのための実際のフィードであるのに十分な詳細を持ちません、しかしそれはフイードが含むような情報を例示します。あなたがアプリによって使われるのを見るだろうJSONは大抵もっと長いです、しかしそれら長いJSON文書は同じクォーティングおよび入れ子の規則に従います。JSONについてのさらなる情報として、ECMA-404: The JSON Data Interchange Formatを見てください。

Not all JSON documents are feeds. Feeds of JSON are informally defined by two characteristics:
全てのJSON文書がフィードであるわけではありません。JSONのフィードは、2つの特徴によって略式に定義されます。

  1. They consist of metadata, like "What's the name of this feed?", and a primary list of homogeneous data items.
    それらは、「このフィードの名前は何か?」のようなメタデータ、そして同種のデータ項目からなる1つの主となるリストから成ります。

  2. They link to, but do not contain, some media of interest (such as a link to an audio file, a blog post, or a playground).
    それらは、幾つかの興味深いメディアへリンクします、しかし含んでいるわけではありません(例えば音声ファイル、ブログ投稿、またはプレイグラウンドへのリンク)。

The feed format used by Swift Playgrounds meets these two characteristics: feeds have some details (metadata) used to name, describe, and identify the subscription; feeds also contain a link to each individual playground book in a subscription.
Swift Playgroundsによって使われるフィード書式はこれら2つの特徴を兼ね備えます:フィードはそのサブスクリプションを命名、説明、そして識別するために使われるいくつかの細目(メタデータ)を持ちます;フィードはまたあるサブスクリプションの中の個々のプレイグラウンドそれぞれへのリンクを含みます。

Update a Subscription by Adding Items to Its Feed
サブスクリプションをそれのフィードに項目を追加して更新する

When you hear something is a subscription, you expect it to be updated over time. The same expectation applies to the feeds distributing your playground subscriptions. Adding, removing, or updating the subscription involves two steps: creating a new or updated playground book, then adjusting the JSON feed so it corresponds to the updates you've just made.
ある物がサブスクリプション(定期購読、配信)であるとあなたが聞きおよぶ時、あなたはそれがやがて更新されることを予想します。同じ予想が、あなたのプレイグラウンドサブスクリプションを配給しているフィードにも当てはまります。サブスクリプションの追加、削除、または更新は2つの段階を必然的に含みます:新規のまたは更新されたプレイグラウンドブックを作成すること、それからあなたがちょうど作成した更新にそれが適合するようJSONフィードを整えること。

When you update a playground book, be sure to update the JSON feed that links to the book at the same time. If the feed is out of date, there may be a mismatch between the preview information contained in the feed and the content in the playground books the feed links to.
あなたがプレイグラウンドブックを更新する時、そのブックにリンクするJSONフィードを同時に更新することを確実にしてください。フィードが古いものならば、フィードに含まれるプレビュー情報とフィードがリンクするプレイグラウンドブックの内容の間に食い違いが生じます。

An Example Subscription Feed
サブスクリプションフィードの例

This example shows a feed with two playground books that make up the whole series. For detailed information about the feed format, see Subscription Feed Format.
この例は、そのシリーズ全体を作り上げる2つのプレイグラウンドを持つフィードを示します。フィード書式についての詳細情報として、サブスクリプションフィード書式を見てください。

  1. {
  2. "title": "Whimsical Swift Syntax",
  3. "subtitle": "A Collection of Swift Lessons",
  4. "publisherName": "Company Name Inc.",
  5. "feedIdentifier": "com.example.whimsicalswift",
  6. "contactURL": "https://support.example.com",
  7. "formatVersion": "1.0",
  8. "documents": [
  9. {
  10. "title": "The Key Path Not Taken",
  11. "overviewSubtitle": "Dynamically Choosing Among Key Paths",
  12. "detailSubtitle": "Because key paths in Swift are applied at runtime, their behavior is dynamic.",
  13. "description": "Learn to compare key paths and pick the right one.",
  14. "contentIdentifier": "com.example.whimsicalswift.keypaths",
  15. "contentVersion": "1.0",
  16. "url": "keypaths/keypaths.playgroundbook.zip",
  17. "publishedDate": "2017-11-13T21:13:57+00:00",
  18. "lastUpdatedDate": "2017-11-13T21:13:57+00:00",
  19. "thumbnailURL": "keypaths/thumbnail.png",
  20. "bannerImageURL": "keypaths/banner.png",
  21. "additionalInformation": [
  22. {
  23. "name": "Languages",
  24. "value": "English"
  25. }
  26. ],
  27. "previewImageURLs": [
  28. "keypaths/preview-1.png"
  29. ]
  30. },
  31. {
  32. "title": "Structer Things",
  33. "overviewSubtitle": "Understand Structures by Comparing Them with Classes",
  34. "detailSubtitle": "Choose between using a structure or a class to model data.",
  35. "description": "Learn about value semantics and reference semantics.",
  36. "contentIdentifier": "com.example.whimsicalswift.structures-and-classes",
  37. "contentVersion": "1.0",
  38. "url": "structures-and-classes/structures-and-classes.playgroundbook.zip",
  39. "publishedDate": "2017-11-13T21:13:57+00:00",
  40. "lastUpdatedDate": "2017-11-13T21:13:57+00:00",
  41. "thumbnailURL": "structures-and-classes/thumbnail.png",
  42. "bannerImageURL": "structures-and-classes/banner.png",
  43. "additionalInformation": [
  44. {
  45. "name": "Languages",
  46. "value": "English"
  47. }
  48. ],
  49. "previewImageURLs": [
  50. "structures-and-classes/preview-1.png"
  51. ]
  52. }
  53. ]
  54. }