Twixl Publisher Documentation

Transcription

1 BUILDING APPS Twixl media Kortrijksesteenweg 1144 N, 9051 Gent (Sint-Denijs-Westrem), Belgium, VAT BE T info@twixlmedia.com Copyright 2017 Twixl media. All Rights Reserved

2 Table of Contentsts General Info... 4 Build Settings overview... 5 Sharing on social media...15 Customizing your app...22 Adding your kiosk app to Apple's Newsstand (pre-ios 9 - Legacy)...25 Using a timer in your app...29 ios Specific...31 Creating provisioning profiles for ios apps...32 ios app build types...35 Android Specific...37 Android app build types...38 About the Android Keystore...39 Single Issue Apps...42 Creating a single-issue app for ios...43 Creating a single-issue app for Android...53 Article-Based Apps...63 Building your article-based app...64 Web Reader...70 Creating a Web Reader export...71 Multi Issue Apps (Legacy)...75 Creating a multi-issue app for ios...76 Creating a multi-issue app for Android...86 Push Notifications...96 General: Sending push notifications...97 ios: Generating a Push SSL Certificate Android: About the Android GCM key Android: About the Android GCM key (> 04/2018) Subscriptions Working with subscriptions for ios

3 Working with subscriptions for Android Entitlement Using the Entitlements option Integrating entitlements in a kiosk infocell Using the Entitlements option for article-based apps

4 General Info Page 4

5 Build Settings overview TIP: In order to get an overview of all available build settings, select "Builds Settings" from the Twixl Publisher menu. Build settings consist of a number of configuration options that determine the type of app that you will be creating, and which features will be enabled in the app. E.g. a build setting can contain the following info: which user interface languages are supported, the artwork (app icon, etc ), whether you are you using Google Analytics, code signing information (provisioning profiles), the app type (issue-based or article-based), etc. Once a build setting has been saved, creating an updated build of the app only requires a few mouse clicks. A build setting can also be exported so it can be used on another Mac (right-click the build setting name to see the options). 1. General Settings This tab provides the following configurations options: User Interface e Languages Select the language support you want for your application - this will make sure that all language strings for the selected languages are included in the app - the language options refer to the error messages that the app will be displaying e.g. when a user is offline, etc. App Store rating Page 5

6 When this option is checked, you can prompt the user of the app to rate it on the store. 2. Analytics Twixl Publisher allows you to integrate analytics in your publications. One the one hand, there is built-in support for analytics in the Twixl Distribution Platform (for kiosk apps only). On the other hand, it is possible to integrate third party analytics: Google Analytics (both single and multiissue apps) and Localytics (multi-issue apps only). You can either use the same key for ios, Android and the Web Reader, or you can define separate keys for each. For Localytics, which allows you to send messages to a subset of your readers, you can enter the keys for ios and Android.You need to create account with the provider of your choice first. The following information will be tracked: Every page viewed Slide shows: every state of a slide show (not for autoplay) Movies: all movies without autoplay Sounds: all sounds without autoplay Web Overlays: all overlays that are displayed Web links: all links that are opened To make your analytics more readable, the Twixl Publisher plug-in allows you to provide your own analytics name to certain interactive objects, such as for slide shows, audio, video, and web overlays. Page 6

7 3. Artwork Icon The app icon that will be displayed in the Home Screen of the device. Should be 1024x1024 pixels in size. You can select a different icon for ios and Android. Startup Screens These screens will be displayed while the app is starting up. They need to have the following dimensions: ipad Portrait: 1536 x 2008 pixels (according to Apple's guidelines, the 40 pixels of the status bar should be removed) ipad Landscape: 2048 x 1496 pixels Android Portrait: 800 x 1232 pixels (full screen less 48 pixels of the System bar) Android Landscape: 1280 x 752 pixels Phones: 640 x 960 pixels, 1242 x 2208 and 2208 x 1242 pixels Page 7

8 4. User interface Tool Bar The tool bar is the top bar that is displayed when you single-tap in a publication, and from where you can return to the store overview. In this pane you can modify the navigation bar background colorand the color of the Text and Icons in the tool bar. The tool bar background color is also used for the progress bars that are displayed when downloading a publication. Scroller Background You can also modify the scroller background color for Android devices, for the Web Reader export and for the iphone 4(s). This color will be used if you are using a publication with a different aspect ratio than your device. The content will be letterboxed and the empty area will display the background color you defined. In most cases you will want this to default to black, but you can choose to use a publication background color that fits best with your content. Page 8

9 5. Inactivity Timer Configuring a timer consists of two things: set a timeout interval (in seconds) define an action URL to be triggered on time-out By default the timeout interval in a build setting will be set to "0", i.e. disabled. The URL action to be triggered can use custom URL schemes for navigation in a Twixl publication. If you want to integrate a timer in a kiosk app, you can also use the URL: tp-store://show This will make sure the app returns to the store overview window after timeout. Page 9

10 6. Sharing Under the "Sharing" tab, you can configure the default shared message for the different platforms. You can choose your own message and insert 3 different placeholders: Application Name Publication Name Article Title You can select whether to add the App Icon or the Issue Cover to the message. You can also add a (short) URL that links to the store if you wish. Readers will be able to share via , Twitter, Facebook, etc. Page 10

11 7. Code signing Code signing is a security measure to provide proof that you are indeed the publisher of an app. ios Code Signing Apple uses a process called "provisioning" for code signing your apps. For more details about provisioning, please refer to the article Creating a provisioning profile. Depending on the type of build you want to create, you may need to create and add different provisioning profiles. For an overview of the different types of ios builds, please refer to this page. IMPORTANT NOTE: If you backup build settings, or copy a build setting to another location, the build setting will include the provisioning profile(s) you have added, but will not include the ios Certificate and private key, as these are taken from the Keychain upon creating the build. If you want to backup the combination of Certificates, Private Keys and Build Settings, just select "Export Developer Identity " from the Tools menu in the Twixl Publisher OS X app. Page 11

12 Android Code Signing Android Application ID This should be a reverse DNS name like com.yourdomain.yourpublication - if you are going to be creating an app for both the ipad and Android, the best practice is to use the same one as the one you used for the ipad. Android Keystore Twixl Publisher normally takes care of creating the "keystore" for you in the background. If you are migrating your app from another platform, such as e.g. Adobe DPS, you will need to import your existing keystore. Check our separate article for more details. 8. App Store Kiosk - Basic Settings Twixl Distribution Platform Application Key Copy the application key from the app you created on the Twixl Distribution Platform platform and enter it here. Newsstand (pre-ios 9) Enable the option "Newsstand" if you want your app to be in Newsstand. This is no longer relevant as of ios9 though. Page 12

13 Android License Key Navigate to Services and APIs for your app to copy the license key for your app Google Cloud Messaging ID required for sending push notifications - also see this article about the Google Cloud Messaging ID. 9. App Store Kiosk - Entitlements Enable entitlements in your app build. This is configured in the build settings under App Store Kiosk - Entitlements. You will need to enter the following parameters: Entitlements URL: you'll find this in the Entitlements configuration window on the Twixl Distribution Platform Entitlements URL style: defines how the urls for the Entitlements Server are constructed. For more information, see Entitlements Server URLs. Entitlements optiuons Require on startup: if enabled, you will need to be entitled before you can access the content in the app. In other words, this allows you to create a "restricted access" app. Login Menu Title: if you want a button to appear in the sidebar menu of the App Store Kiosk that can trigger the entitlements signin form, you can enter the title for the button here, e.g. "Already a subscriber?". Logout Menu Title: if you want the menu title to change when the user is logged in, you can enter a different title here. For more info about Entitlements, refer to our separate article. Page 13

14 10. App Store Kiosk - User Interface Here you can change the images that will be used to style the storefront. You can drag and drop images in the sizes specified for the store background. Using an info page or an info cell (banner)) in your kiosk You can choose to display an info page that is triggered by a menu item in the sidebar menu of the kiosk. You need to create an HTML document called "infopage.html" and add that to the WebResources folder. The title of the menu item can be entered here. You can also include a banner at the top of the store. You need to create an HTML document called "infocell.html" and add that to the WebResources folder. The infocell height can be different for landscape/portrait and for ipads, Android tablets and phones. On phones, the kiosk only supports portrait orientation. For detailed information about these options, refer to this article. Page 14

15 Sharing on social media Social sharing allows the reader to share an article via social media or default mobile device sharing options. This article explains how to prepare both your app and content for that feature. 1. What does the reader see? Readers will be able to share via , Twitter, Facebook,... (depending on the OS and the installed applications). The result will be similar to the screenshot below. Page 15

16 2. How to configure for article-based apps 2.1. Activating the option on the Twixl Distribution Platform There is only 1 requirement to enable Social Sharing in an article-based app: you need to activate the option in the Application Settings of your article-based app. For more info, see this KB-article Configuring Social Media metadata Social Sharing works for Content Items. Each Content Item can have specific metadata for your Social Sharing. Page 16

17 Available options Text for Social Sharing: The default text you want to use for social sharing. This text will be inserted for your readers when he/she wants to share an article. Article URL: In order to be able to share over social media, an article URL is required. Leave this field empty to use the Browser Client URL (if you have enabled the browser client for your app). For more info about the Browser Client, see this KB-article Possible scenarios No Article URL defined + Browser Client t enabled: the reader will be able to share the article, with the Browser Client URL. Custom Article URL defined + Browser Client t enabled or disabled: the reader will be able to share the article, with the custom Article URL. No Article URL defined + Browser Client t disabled: your reader will not be able to share the article. REQUIRED FIELDS: As a publisher, it is not required that the text for Social Sharing is filled in, in order to activate Social Sharing. Only the Article URL is mandatory. Page 17

18 3. Configuring for single issue and issue-based apps 3.1. Allow sharing on social media If you want to provide a sharing option to readers of your publication, make sure the option "Allow Sharing on Social Media" is enabled in the Publication Properties of the plug-in or in the Publication properties of the Publication Composer. Page 18

19 NOTE: Using the "Sharing" option also requires you use the TOC Viewer with the Title Bar Button. It cannot be used with the legacy thumbnail viewer. Page 19

20 3.2. Configure the default sharing message In the Build Settings of the Twixl Publisher application, under the "Sharing" tab, you can configure the default shared message for the different platforms. You can choose your own message and insert 3 different placeholders: Application Name Publication Name Article Title Article URL: this is ideal if you want to link to e.g. a Web Reader version of your content You can also add an app-wide (short) URL that links to the store. Page 20

21 3.3. Configuring the article URL If you want your sharing message to have a customized URL per article, that can be configured in the Article properties. This may be a good option if you also have a Web Reader version of your content that is publicly accessible Artwork to share You can select to either share the app icon or the issue cover. Page 21

22 Customizing your app Configuring the build settings Several customization options are available in the build settings of your app. Some options are available in the "User Interface" part of the build settings (these apply to both singleand multi-issue apps). App Store only settings are available in the "App Store Kiosk - User Interface" tab. Tool Bar & Scroller Background colors You can set the background color, as well as the color for the Text and Icons to be used in the toolbar. You can also modify the scroller background color for Android devices and for the Web Reader export. This color will be used if you are using a publication with a different aspect ratio than your device. The content will be letterboxed and the empty area on the left and right will display the background color you defined. In most cases you will want this to default to black, but you can choose to use a publication background color that fits best with your content. App Store Kiosk options Here you can change the images that will be used as the background image for the storefront. You can drag and drop images according to the sizes specified for the store backgrounds. Depending on the background you selected, you can optionally change the "Grid Text Color" - the text that is displayed under the issue cover in the store. Page 22

23 Using an info page in your kiosk ("infopage") You can choose to display an info page that will be place don top of your kiosk top of the store. An Info page is a page that can be called by selecting a menu in the sidebar of the kiosk (enter the title in the "Side Menu Title" field - leave this field blank if you don't want this menu item to appear at all). You can also trigger the infopage to be displayed from the infocell by using the special URL scheme: tp-info-page://self Here you can introduce users to your app or e.g. to information about your company, etc. To provide an info page, you ll have to create an HTML page, called exactly infopage.html, and copy this page to the Web resources folder of your build setting (click the "Web Resources" button to go to that location). If you want to display online content you can check whether the device is connected to the internet and then redirect to your online page (see also this article). Using a banner in your kiosk ("infocell") You can also choose to display an extra banner at the top of the store, called an "infocell". An "infocell" is essentialy the same as an Info page, the only difference is the way it is presented to your users. The info cell is like a header for your store. You'll need to create an HTML file, named exactly Page 23

24 infocell.html, that you should also place in the Web Resources folder of your build setting. You can easily implement the same online-offline check as above. The infocell height and width can be different for ipads, Android tablets and phones. If you want to display online content you can check whether the device is connected to the internet and then redirect to your online page (see also this article). Page 24

25 Adding your kiosk app to Apple's Newsstand (pre-ios 9 - Legacy) Configuring Newsstand in the build settings Previously, Apple provided a way to organize your magazine and newspaper app subscriptions in Newsstand. This is no longer the case with ios 9. If you want your app to appear in Apple's Newsstand, just create your multi-issue app and enable the option "Newsstand" in the Build Settings for your app in the Twixl Publisher application. Select the binding style and edge type - in most cases you'll want to use the default values. IMPORTANT NOTE: Even if you create a Newsstand app with the initial cover image, you still need the standard home screen icon as well. Newsstand requirements In order for an app to be allowed in Newsstand, your app must have: Newsstand enabled in itunes Connect, but you will be managing your content in the Twixl Distribution Platform An auto-renewable subscription as an in-app purchase option Page 25

26 Subscription If you are publishing paid content, then you will need to define an Auto-Renewable Subscription. For free content, you need to define a Free Subscription. Adding issues manually Every time you want to add a new issue to a Newsstand app, you will have to create a new entry in itunes Connect and upload the cover of the issue. Page 26

27 Adding issues automatically via an Atom feed Instead of manually adding an entry itunes Connect for each of your issues, the Twixl Distribution Platform can take care of that automatically for you if you add the 'Atom Feed' for your app Login to your account on the Twixl Distribution Platform, go to the detail of your app, and copy the Newsstand Atom Feed URL, that you'll find there. Now paste the URL in the Atom Feed URL field in itunes Connect. Now, every 24 hours, Apple will automatically check whether new content is available. Page 27

28 Page 28

29 Using a timer in your app Ideal for trade shows s If you want to use a Twixl-based app in a "kiosk" type of environment, e.g. for ipads on display at a trade show, you may want to integrate an inactivity timer that returns to a certain start situation after being idle for a while. If you have trade show visitors, then you can decide that after a specified amount of idle time, the publication needs to return to the starting page, to make sure a new visitor doesn't get lost Configuration Configuring a timer consists of two things: Page 29

30 set a timeout interval (in seconds) define an action URL to be triggered on time-out By default the timeout interval in a build setting will be set to "0", i.e. disabled. The URL action to be triggered can use custom URL schemes for navigation in a Twixl publication. If you want to integrate a timer in a kiosk app, you can also use the URL: tp-store://show This will make sure the app returns to the store overview window after timeout. You can also use the following URL schemes to pause/remuse playback of background music: tp-background-music://pause tp-background-music://resume Page 30

31 ios Specific Page 31

32 Creating provisioning profiles for ios apps A requirement to create an ipad app Follow the steps below to create a provisioning profile Apple built a security model for ios that requires a combination of a security certificate and a private key in order to 'codesign' apps and be able to either install them on an ipad outside of the App Store, or to submit them for review in the App Store. Below we are describing the steps required to create your own provisioning profiles. More detailed documentation about provisioning profiles is available from Apple's developer portal. 1. Obtain your ios Distribution Certificate Login to Apple's Developer Member Center, then select "Certificates, Identifiers & Profiles". Click the "How To" tab to get information on how to generate a certificate signing request and download an ios Distribution Certificate. Although the "How To" may describe the procedure for obtaining a Development t Certificate, it is exactly the same for obtaining a Distribution Certificate. At the end of this procedure, you will need to have downloaded and installed a Distribution Certificate. A Distribution Certificate identifies your development team. When it s stored in your keychain, it includes the team s private key. IMPORTANT NOTE: Twixl Publisher uses Development Certificate and Development provisioning profiles for testing Page 32

33 purposes, and a Distribution Certificate and Distribution provisioning profile for Ad Hoc and App Store distribution. IMPORTANT NOTE FOR TEAMS: If the certificate has already been created (e.g. by a colleague), then the easiest procedure is to ask that colleague to export the combination of the distribution certificate and the private key using the Keychain Access application. Exporting those 2 items will generate a file with extension.p12 - open this on your own computer to add them via the Keychain Access application. Alternatively, it is also possible to select "Export Developer Identity" from the Tools menu in the Twixl Publisher app. 2. Assign the devices Now you need to assign the devices you want to use for your Ad Hoc builds. Locate the Unique device ID in itunes (click on "Serial Number" and the Identifier will be displayed - copy the UDID via cmd-c). Now add the UDID(s) to the 'Devices' section of the ios Provisioning Portal. You'll find more information about this via the "How To" tab. IMPORTANT NOTE: Adding these devices is only required for creating "Ad Hoc" test builds for internal use. 3. Create an App ID An App ID consists of a universally unique 10 character "Bundle Seed ID" prefix generated by Apple and a "Bundle Identifier". The recommended practice is to use a reverse-domain name style string for the "Bundle Identifier" portion of the App ID, e.g. com. om.yourdomain. domain.yourpublication. Again, you'll find more information in the "How To" tab. IMPORTANT NOTE: Page 33

34 You should not use a wildcard app ID (i.e. an asterisk) for your application. 4. Create and download a Distribution Provisioning Profile In order to build your application for Ad Hoc distribution, you will need to create and download an Ad Hoc Distribution Provisioning Profile. Follow Apple's instructions via the "How To" tab of the "Provisioning" menu. Although the "How to" describes the procedure for creating Development Provisioning Profiles, it is exactly the same for creating a Distribution Provisioning Profile. 5. Building your app Keep the provisioning profile you just created at hand. You will need it during the 'build' process. Once you have gone through the process of generating an "Ad Hoc" provisioning profile, you'll also be able to follow the same procedure to create an "App Store" provisioning profile. You will need this profile when you are ready to create a build of your app to submit to the App Store. Page 34

35 ios app build types Different t provisioning profiles for different t build types Depending on the type of build you want to create, you'll use one of four types of distribution provisioning profiles: Development provisioning profile Ad Hoc provisioning profile Enterprise provisioning profile App Store provisioning profile 1. Development t build When using Twixl Publisher, a development build is going to be required only when testing push notifications in an App Store Kiosk app. 2. Ad Hoc build ios Developers enrolled in the standard ios Developer program have the opportunity to distribute their application outside of the App Store on up to 100 different devices. Use the "Ad Hoc" provisioning profile created in the ios Provisioning Portal to distribute a build of your publication internally. Page 35

36 3. Enterprise build ios Developers enrolled in the ios Developer Enterprise program have the opportunity to distribute their application outside of the App Store and without the 100 devices limit. Use the "Enterprise" provisioning profile created in the ios Provisioning Portal to distribute a build of your publication internally. 4. App Store build Use the "App Store" provisioning profile created in the ios Provisioning Portal to create a build that you will be submitting to the App Store. The application will automatically be zipped so it's ready for upload to itunes Connect. In order to create any type of build, the build settings for your app must contain the relevant provisioning profile. Page 36

37 Android Specific Page 37

38 Android app build types Different t build types Depending on the type of build you want to create, you'll use one of three types: Android Test Build Android for Google Play Test Build The Android Test build, as the name implies, is for testing purposes only. A test build can be installed on a device via an SD card. Google Play A build of the app that you will be submitting to the Google Play store. In order to create any type of build, the build settings for your app must contain an Android application ID. Page 38

39 About the Android Keystore IMPORTANT INFO ABOUT GOOGLE PLAY APP SIGNING Read this important information about Google Play App Signing here, before you start uploading applications to Google Play! When you publish an app in the Google Play store, Google expects that app to be signed with a certificate. When you create an Android app with Twixl Publisher, we take care of creating this "keystore" for you in the background. Every update of your app will have to be signed using the same keystore information (the app's "fingerprint" so to speak), otherwise it will not be accepted on Google Play. IMPORTANT NOTE: The keystore information will be saved as part of the build setting for that app. This means that, if you migrate to a different machine, you will have to make sure to also migrate the build setting. Either use the option "Export Developer Identity" from the 'Tools' menu in the Twixl Publisher application, or right-click on a build setting to reveal it in then Finder and copy it manually. Page 39

40 IMPORTANT: Note that if you ever lose the keystore information, there is no other way to retrieve it, you will be unable to update the app in the future. However, we have changed the behavior for new build settings created with version or higher: a keystore is now generated once for your account (based on your account ID) and is used for all new build settings. That way, all build settings will be using the same Android keystore. Migrating your Google Play app from another platform, such as Adobe DPS, etc. If you are moving to Twixl Publisher from a platform like Adobe DPS, you will have created an Android keystore using the Keytool via terminal, according to the instructions outlined in Adobe's documentation. During that process you generated a keystore with an extension ".p12". In order to update your existing Adobe DPS app to an app created with Twixl Publisher, you can use the 'Import' option in the Code Signing tab of the build settings for that app. When importing the.p12 keystore, you will also need to provide the password you used to create it. Page 40

41 Page 41

42 Single Issue Apps Page 42

43 Creating a single-issue app for ios Use the build settings wizard to go through the process step by step. When creating an app build for the first time, a configuration wizard will walk you through the different steps and options of the build process. Once you saved that setting, you will be able to re-use it later for generating an update of that app. Below is an overview of the different steps involved for creating a single-issue ipad app. 1. Choose a name for your setting Usually the build setting name will refer to the publication name. 2. Choose the Application Type Here you can select the type of app you wish to build: Page 43

44 Single Issue This will generate a standalone app that contains the contents for a single issue of your publication. When creating an update of this app, all existing contents will be replaced by the new version. ipad apps can be submitted to Apple via itunes Connect. Page 44

45 3. General Settings 3.1. General Application name This is the name users will see on the home screen of the device. Build For Choose whether you want an app that supports Tablets, Phones, or both UI Languages Here you can select the languages your app will support - alerts and error messages in your app will then be displayed in the system language specified on the device App Store Rating If you want to prompt the reader to rate your app on the app store, you need to check this option. Page 45

46 4. Analytics 4.1. Google Analytics If you want to gather analytics data for your publication, enter your web tracking code in the form of UA-XXXXX-Y. You need to have a Google Analytics account to do this. In that account, create a mobile app entry for your publication. Full analytics setup info is available here Localytics Localytics can only be used with Multi-Issue Apps 4.3. Twixl Publisher Platform Twixl Publisher Platform Analytics are not possible for Single-Issue Apps. Page 46

47 5. Artwork 5.1. App Icon The app icon that will be displayed in the Home Screen of the device. Should have a size of 1024x1024 pixels Startup Screens for Tablets These screens will be displayed while the app is starting up (if you do not select any images, the default ones will be used). They need to have the following dimensions: ios Porttrait: 1536 x 2008 pixels (according to Apple's guidelines, the 40 pixels of the status bar should be removed) ios Landscape: 2048 x 1496 pixels 5.3. Startup Screens for Phones These screens will be displayed while the app is starting up (if you do not select any images, the default ones will be used). They need to have the following dimensions: Portrait (4:3): 640 x 960 pixels Portrait (16:9): 1242 x 2208 pixels Page 47

48 Landscape (16:9): 2208 x 1242 px 6. Code Signing Code signing is a security measure to provide proof that you are indeed the publisher of an app. ios Code Signing Apple uses a process called "provisioning" for code signing your apps. For more details about provisioning, please refer to the article Creating a provisioning profile. Depending on the type of build you want to generate, you may need to create and add different provisioning profiles. For an overview of the different types of ios builds, please refer to this page. Page 48

49 7. Create build Your are now ready to create a build of your app, according to the settings you specified. Later on you can also check the "Advanced Settings" to adjust more advanced settings that are not included in the wizard. Page 49

50 8. Application options When you create a build, you will get different options for your build, as shown below: Version Allows you to increment the version when you are updating your app Platforms ios - make sure that you have at least one provisioning profile available in the build setting. For an overview of the different ios app builds, check this article. Publication Select the InDesign export file here (with the.publication extension) Options "Generate Over-the-Air install files": check the article about in-house ios deployment for more info. Page 50

51 9. Build process The app will display information about the current build status. Page 51

52 10. Build succesful! When the build process has completed, you will be able to navigate to the resulting file in the Finder 11. Resulting file When you open the folder called "ipad" you'll find the app named according to the reverse DNS of your app id, and with an extension ".ipa". You are now ready to deploy your app in-house or to the App Store. Page 52

53 Creating a single-issue app for Android Use the build settings wizard to go through the process step by step When creating an app build for the first time, a configuration wizard will walk you through the different steps and options of the build process. Once you saved that setting, you will be able to re-use it later for generating an update of that app. Below is an overview of the different steps involved for creating a single-issue Android app. 1. Choose a name for your setting Usually the build setting name will refer to the publication name. 2. Choose the Application Type Here you can select the type of app you wish to build: Page 53

54 Single Issue This will generate a standalone app that contains the contents for a single issue of your publication. When creating an update of this app, all existing contents will be replaced by the new version. Android apps can then be submitted to Google Play. Page 54

55 3. General Settings 3.1. General Application name This is the name users will see on the home screen of the device. Build for Choose whether you want an app that supports Tablets, Phones, or both UI Language Here you can select the languages your app will support - alerts and error messages in your app will then be displayed in the system language specified on the device App Store Rating If you want to prompt the reader to rate your app on the app store, you need to check this option. Page 55

56 4. Analytics 4.1. Google Analytics If you want to gather analytics data for your publication, enter your web tracking code in the form of UA-XXXXX-Y. You need to have a Google Analytics account to do this. In that account, create a mobile app entry for your publication. Full analytics setup info is available here Localytics Localytics can only be used with Multi-Issue Apps 4.3. Twixl Publisher Platform Twixl Publisher Platform Analytics are not possible with Single-Issue Apps. Page 56

57 5. Artwork 5.1. App Icon The app icon that will be displayed in the Home Screen of the device. Should have a size of 1024x1024 pixels Startup Screens for Tablets These screens will be displayed while the app is starting up (if you do not select any images, the default ones will be used). They need to have the following dimensions: Android Portrait: 800 x 1232 pixels Android Landscape: 1280 x 752 pixels 5.3. Startup Screens for Phones These screens will be displayed while the app is starting up (if you do not select any images, the default ones will be used). They need to have the following dimensions: Portrait (4:3): 640 x 960 pixels Portrait (16:9): 1242 x 2208 pixels Landscape (16:9): 2208 x 1242 px Page 57

58 6. Code Signing Code signing is a security measure to provide proof that you are indeed the publisher of an app. Android Code Signing Android Application ID This should be a reverse DNS name like com.yourdomain.yourpublication - if you are going to be creating an app for both the ipad and Android, the best practice is to use the same one as the one you used for the ipad. Android Keystore If you are moving to Twixl Publisher from a platform like Adobe DPS, you will have created an Android keystore using the Keytool via terminal. You can find more info about the Android Keystore in this article. Page 58

59 7. Create build Your are now ready to create a build of your app, according to the settings you specified. Later on you can also check the "Advanced Settings" to adjust more advanced settings that are not included in the wizard. Page 59

60 8. Application options When you create a build, you will get different options for your build, as shown below: Version Allows you to increment the version when you are updating your app Platforms Android - select Test build to create a version for internal testing, Android for Google Play for submitting to the Play store. Publication Select the InDesign export file here (with the.publication extension) Page 60

61 9. Build process The app will display information about the current build status. Page 61

62 10. Build succesful! When the build process has completed, you will be able to navigate to the resulting files in the Finder. 11. Resulting file(s) For a test build The resulting file will have an extension.apk You are now ready to deploy your app For a Google Play build There will be two files: a file with extension.apk (the app itself) a file with extension.obb (the publication) You are now ready to deploy your app. Page 62

63 Article-Based Apps Page 63

64 Building your article-based app The Twixl Publisher 5 builder app lets you create a new app type in addition to the legacy single-issue and multi-issue apps: an article-based app. 1. Choose a name for your setting Page 64

65 2. Application Type When creating a new build setting, select "Article-based app" as the Application type. Page 65

66 3. General 3.1. General Application name This is the name you will see on your device home screen. Build For Choose whether you want an app that supports Tablets, Phones, or both User Interface e Languages Here you can select the languages your app will support - alerts and error messages in your app will then be displayed in the system language specified on the device. Page 66

67 4. Artwork App Icon Add a 1024x1024 icon for ios and/or Android. Launch Image And add a 2208 x 2208 square image that will be used as the launch image. Page 67

68 5. Code Signing For more information on code signing, please refer to this article. Page 68

69 6. Application Key Copy the application key from the article-based app you created on the Twixl Publisher Platform and enter it here. For Android, navigate to Services and APIs for your app on the Google Play portal to copy the license key for your app. 7. Build your app Your are now ready to build your app and submit it to itunes Connect and/or Google Play. Page 69

70 Web Reader Page 70

71 Creating a Web Reader export Use the build settings wizard to go through the process step by step When creating an app build for the first time, a configuration wizard will walk you through the different steps and options of the build process. Once you saved that setting, you will be able to re-use it later for generating an update of that app. Below is an overview of the different steps involved for creating a Web Reader export for distribution on desktops and notebooks. 1. System Requirements When using the web reader, you need to use a web browser that supports HTML5. The Twixl Web Reader is supported with the following browser versions: Safari 5 or newer Google Chrome 18 or newer Internet Explorer 9 or newer FireFox 22 or newer NOTE: Video in a Web Reader will not be displayed in Firefox, because that browser does not support the.mp4 video encoding standard. If a landscape layout for your publication is available, the web reader will automatically default to that format, and it will not generate a portrait version. 2. Choose a name for your setting Usually the build setting name will refer to the publication name. 3. General Settings 3.1. Application Name This is the name users will see in the title bar of the browser. Page 71

72 Twixl Publisher Documentation 3.2. Languages Language support is irrelevant for this type of export Google Analytics If you want to gather analytics data for your publication, enter your web tracking code in the form of UA-XXXXX-Y. You need to have a Google Analytics account to do this. In that account, create an entry for your publication. Full analytics setup info is available here it itunes unes S Stor toree Application ID & Smart App Banners (>5.6) Safari has a nice tool in ios 6+ that provides a standardised method of bannering apps on the App Store from a website. Twixl Publisher Web Readers have built-in support for that (since Twixl Publisher 5.6). 1. You need yyour our app-id fr from om it itunes unes. To find your app ID from the itunes Link Maker, type the name of your app in the Search field, and select the appropriate country and media type. In the results, find your Page 72

73 app and select iphone App Link in the column on the right. Your app ID is the nine-digit number in between id and?mt. 2. Next, you need to copy-paste that nine-digit number in your Build Setting. See screenshot 4. Skip Artwork & Code signing Both are irrelevant for a Web Reader export. 5. App type Here you can select the type of app you wish to build: 5.1. Single issue A Web Reader export will always be for a single publication. This will generate a set of HTML files that can then be deployed on any web server. 6. Create build Your are now ready to create a Web Export. Page 73

74 7. Application options When you create a build, you will get different options for your build, as shown below: Version Allows you to increment the version when you are updating your app Platforms Web Reader Publication Select the InDesign export file here (with the.publication extension) 8. Build process The app will display information about the current status. 9. Build succesful! When the export process has completed, you will be able to navigate to the resulting folder in the Finder. You are now ready to deploy your Web Reader. Page 74

75 Multi Issue Apps (Legacy) Page 75

76 Creating a multi-issue app for ios Use the build settings wizard to go through the process step by step When creating an app build for the first time, a configuration wizard will walk you through the different steps and options of the build process. Once you saved that setting, you will be able to re-use it later for generating an update of that app. Below is an overview of the different steps involved for creating a multi-issue ipad app. 1. Choose a name for your setting Usually the build setting name will refer to the publication name. 2. App type Here you can select the type of app you wish to build: Page 76

77 App Store Kiosk This will generate a kiosk app that will essentially be an empty shell. Page 77

78 3. General Settings 3.1. General Application name This is the name users will see on the home screen of the device. Build For Choose whether you want an app that supports Tablets, Phones, or both UI Languages Here you can select the languages your app will support - alerts and error messages in your app will then be displayed in the system language specified on the device App Store Rating If you want to prompt the reader to rate your app on the app store, you need to check this option. Page 78

79 4. Analytics 4.1. Google Analytics If you want to gather analytics data for your publication, enter your web tracking code in the form of UA-XXXXX-Y. You need to have a Google Analytics account to do this. In that account, create a mobile app entry for your publication. Full analytics setup info is available here Localytics For Localytics, which allows you to send messages to a subset of your readers, you can enter the keys for ios and Android Twixl Publisher Platform For multi-issue apps, the Twixl Distribution Platform will gather an extensive list of analytics data for you automatically, without the need for Google Analytics intgration. Page 79

80 5. Artwork 5.1. App Icon The app icon that will be displayed in the Home Screen of the device. Should have a size of 1024x1024 pixels Startup Screens for Tablets These screens will be displayed while the app is starting up (if you do not select any images, the default ones will be used). They need to have the following dimensions: ios Porttrait: 1536 x 2008 pixels (according to Apple's guidelines, the 40 pixels of the status bar should be removed) ios Landscape: 2048 x 1496 pixels 5.3. Startup Screens for Phones These screens will be displayed while the app is starting up (if you do not select any images, the default ones will be used). They need to have the following dimensions: Portrait (4:3): 640 x 960 pixels Portrait (16:9): 1242 x 2208 pixels Page 80

81 Landscape (16:9): 2208 x 1242 px 6. Code Signing Code signing is a security measure to provide proof that you are indeed the publisher of an app. ios Code Signing Apple uses a process called "provisioning" for code signing your apps. For more details about provisioning, please refer to the article Creating a provisioning profile. Depending on the type of build you want to generate, you may need to create and add different provisioning profiles. For an overview of the different types of ios builds, please refer to this page. 7. App Store Kiosk Settings Before you can enter the details below, you will first need to go through the process of adding an app in the Twixl Distribution Platform. Once you've done that, copy the application key for that app and enter it here. Page 81

82 Select whether or not you want the app to be available in Apple's Newsstand. Note that checking this box also means you need to define a subscription. 8. Create build Page 82

83 Your are now ready to create a build of your app, according to the settings you specified. Later on you can also check the "Advanced Settings" to adjust settings that are not part of the default wizard. 9. Application options When you create a build, you will get different options for your build, as shown below: Version Allows you to increment the version when you are updating your app Platforms ipad - make sure that you have at least one provisioning profile available in the build setting. For an overview of the different ipad app builds, check this article. Publication As a multi-issue app starts as an empty app, there is no need to select a publication. Options "Generate Over-the-Air install files": check the article ipad deployment for more info. Page 83

84 10. Build process The app will display information about the current build status. Page 84

85 11. Build succesful! When the build process has completed, you will be able to navigate to the resulting file in the Finder. 12. Resulting file When you open the folder called "ipad" you'll find the app named according to the reverse DNS of your app id, and with an extension ".ipa". You are now ready to deploy your app in-house or to the App Store. Page 85

86 Creating a multi-issue app for Android Use the build settings wizard to go through the process step by step When creating an app build for the first time, a configuration wizard will walk you through the different steps and options of the build process. Once you saved that setting, you will be able to re-use it later for generating an update of that app. Below is an overview of the different steps involved for creating a multi-issue Android app. 1. Choose a name for your setting Usually the build setting name will refer to the publication name. 2. App type Here you can select the type of app you wish to build: Page 86

87 App Store Kiosk This will generate a kiosk app that will essentially be an empty shell. Page 87

88 3. General Settings 3.1. General Application name This is the name users will see on the home screen of the device. Build For Choose whether you want an app that supports Tablets, Phones, or both UI Languages Here you can select the languages your app will support - alerts and error messages in your app will then be displayed in the system language specified on the device App Store Rating If you want to prompt the reader to rate your app on the app store, you need to check this option. Page 88

89 4. Analytics 4.1. Google Analytics If you want to gather analytics data for your publication, enter your web tracking code in the form of UA-XXXXX-Y. You need to have a Google Analytics account to do this. In that account, create a mobile app entry for your publication. Full analytics setup info is available here Localytics For Localytics, which allows you to send messages to a subset of your readers, you can enter the keys for ios and Android Twixl Publisher Platform For multi-issue apps, the Twixl Distribution Platform will gather an extensive list of analytics data for you automatically, without the need for Google Analytics intgration. Page 89

90 5. Artwork 5.1. App Icon The app icon that will be displayed in the Home Screen of the device. Should have a size of 1024x1024 pixels Startup Screens for Tablets These screens will be displayed while the app is starting up (if you do not select any images, the default ones will be used). They need to have the following dimensions: Android Portrait: 800 x 1280 pixels Android Landscape: 1280 x 800 pixels 5.3. Startup Screens for Phones These screens will be displayed while the app is starting up (if you do not select any images, the default ones will be used). They need to have the following dimensions: Portrait (4:3): 640 x 960 pixels Portrait (16:9): 1242 x 2208 pixels Landscape (16:9): 2208 x 1242 px Page 90

91 6. Code Signing Code signing is a security measure to provide proof that you are indeed the publisher of an app. Android Code Signing This should be a reverse DNS name like com.yourdomain.yourpublication - if you are going to be creating an app for both the ipad and Android, the best practice is to use the same one as the one you used for the ipad. 7. App Store Kiosk Settings Before you can enter the details below, you will need to go through the process of adding an app in the Twixl Distribution Platform. Once you've done that, copy the application key from the platform and enter it here. Now make sure to add your app in the Google Play Developer Console and select "Services & APIs", then copy the license key for your app, then paste it in the "Android License Key" field. Page 91

92 8. Create build Your are now ready to create a build of your app, according to the settings you specified. Later on you can also check the "Advanced Settings" to adjust more advanced settings that are not included in the wizard. Page 92

93 9. Application options When you create a build, you will get different options for your build, as shown below: Version Allows you to increment the version when you are updating your app Platforms Android - select Test build to create a version for internal testing or Android for Google Play for submitting to the Play store. Publication As a multi-issue app starts as an empty app, there is no need to select a publication. Options Irrelevant for Android. Page 93

94 10. Build process The app will display information about the current build status. Page 94

95 11. Build succesful! When the build process has completed, you will be able to navigate to the resulting file in the Finder. 12. Resulting file The result will be a file with extension.apk You are now ready to deploy your app. Page 95

96 Push Notifications Page 96

97 General: Sending push notifications A notification is a great way to let the users know you have a new issue available. 1. To start Before you can start sending push notifications, make sure the required push notification information has been added for your app in the Distribution Platform. Notifications can be sent automatically when a new issue is published, or you can navigate to the top level "Notifications" menu to send a push notification manually. IMPORTANT NOTE: If you activate push notifications for an existing App Store app, an update of the app will need to be submitted. 2. Certificates ios Certificate (P12) Your.p12 certificate, exported from your Keychain. How to get your ios certificate for Push Notifications? ios Certificate Password Page 97

98 The password you have selected when exporting the.p12 from your Keychain. Android GCM Key Your 'Google Cloud Messaging' key. How to get your Android GCM Key? When everything is correctly configured, you can select "Send Notification". This message will be sent to all the devices that have installed your app, and that have opted to receive notifications. 3. Testing In order to send push notifications, you need to register some test devices (phones, tablets) first. The procedure to register a test device is explained below. There is a small difference between issuebased and article-based apps Registering a test-device in an Issue-based apps (legacy) In order to allow you to test push notifications before you submit your app in the App Stores, select "Device info" from the sidebar hamburger-menu icon in the top left corner. NOTE: The "Device info " menu is not available in App Store builds. Page 98

99 At the bottom of the popup window, tap "Register" to register your device as a test device. After tapping "Register" you will be able to select the device for testing in the Twixl Distribution Platform. Page 99

100 3.2. Registering a test-device in an article-based application In order to allow you to test push notifications before you submit your app in the App Stores, select "Device info" from the gear-menu icon in the top right corner. NOTE: The "Register As Test Device" menu is not available in App Store builds. At the bottom of the popup window, tap Register As Test Device to register your device as a test device. Page 100

101 TIP FOR ARTICLE-BASED APPLICATIONS WITH A HAMBURGER MENU ACTIVATED TED (> TP 5.5.x): Since Twixl Publisher 5.5+, you can add a Hamburger Menu to your article-based application. If you've activated that Hamburger Menu, you can find the Gear Menu in the bottom right corner of that Hamburger Menu: Page 101

102 3.3. Sending Push Notifications to test-devices Sending Push Notifications to test-devices is done on our Twixl Distribution Platform from within your application menu (both for issue-based and article-based applications). Page 102

103 NOTE: You will only be able to start sending notifications, when your app has been installed and opened on at least 1 device. Also note that you can only send 1 push notification per 24 hours to a Newsstand app in the App Store. Other apps do not have this limitation. 4. Newsstand push notifications (pre-ios 9) A Newsstand push notification can either be sent when publishing the issue, or can be sent manually using 'Notify' in the issue details. A Newsstand push notification will update the cover in the Newsstand to the cover of that issue and display a blue dot below the app icon to demonstrate that new content is available. Page 103

104 ios: Generating a Push SSL Certificate 1. Setup an App ID Go to https: /developer.apple.com -> Member Center -> Certificates, Identifiers & Profiles -> Identifiers. If you want to edit an existing App ID, select 'Configure', otherwise select 'New App ID'. After you entered a description for this App ID and the Bundle Identifier (use the same reverse-dns name as in the Twixl Distribution Platform) you can configure it. 2. Activate push notifications for the App ID When in the App ID detail window, you'll notice a list of all App Services. Enable for Apple Push Notifications. Page 104

105 3. Development or production When you activate Push notifications for your App ID, you'll notice that Push notifications can be configured. From there on, you can either generate a Development SSL certificate (for use with a Development test app on the Twixl Distribution Platform) or a Production SSL Certificate (for use with a production app on the Twixl Distribution Platform that you'll be submitting to the App Store). Page 105

106 4. Create a Certificate Signing Request Create a cerificate signing request in the Keychan Access application on your Mac. Page 106

107 5. Upload the signing request Page 107

108 6. Generate & download the certificate, and add it to your Keychain Download your certificate, then double-click the file with extension.cer to add it to your Keychain. Page 108

109 7. Export your ios Push Certificate Open the Twixl Publisher application, and select "Export Push Notification Certificate " from the Tools menu. Page 109

110 Select the push certificate for your app, then enter a password (you will need it later), and save the file, that will have an extension.p12 8. Upload the.p12 file to the Twixl Distribution Platform On the Twixl Distribution Platform, navigate to your app, then select Push Notifications. In the settings, upload the.p12 and make sure to enter the correct password. IMPORTANT NOTE: Make sure to upload a Development Certificate in a test app, and a Production Certificate for a production app. Page 110

111 Android: About the Android GCM key ABOUT THE MOVE TO FIREBASE: Recently, Google sent out info about the switch to Firebase. This is the current situation: All existing apps linked to existing GCM Projects will continue to work just fine. Next year (April 2019), we will have to be ready for the final move to Firebase but we'll handle this move as a High Priority Change. We will be ready! The procedure to create new GCM Projects still exists but has changed a lot. This KB-article explains you the new procedure! Required for sending push notifications on Android. You can find the new instructions in this KB-article. Page 111

112 Android: About the Android GCM key (> 04/2018) ABOUT THE MOVE TO FIREBASE: Recently, Google sent out info about the switch to Firebase. This is the current situation: All existing apps linked to existing GCM Projects will continue to work just fine. Next year (April 2019), Twixl will have to be ready for the final move to Firebase but we'll handle this move as a High Priority Change. We will be ready! The procedure to create new GCM Projects still exists but has changed a lot. This KB-article explains the new procedure! In this KB-article, we explain the procedure to setup Push Notifications for Android. 1. Get Started 1. Go to https: /console.firebase.google.com/ 2. Signin with a Google Account. 3. Go to the Console. Page 112

113 TIP: If you login with a Google Account that is linked to a Google Play Developer account, you can link your Firebase Projects (and apps) more easily to your Android apps in the Google Play Developer Console. However, this is not a requirement to setup your Push Notifications for a Twixl Publisher issue-based or article-based application. ABOUT THE OLD GCM CONSOLE (< 04/2018): The old url https: /developers.google.com/mobile/add will automatically redirect to the new FireBase Console. Handy for people that like to manage their bookmarks: you don't need to update your bookmark! 2. Add a Project 1. Click on Add Project. 2. Choose a Project Name (e.g. the name of your app: My Magazine ). You can also choose an existing Project to setup Firebase for. 3. Choose a Project ID or accept the proposed one. You cannot change the project ID after you create it. 4. Choose your Country/region (e.g. Belgium ). 5. Click on Create Project. 6. Wait for the Project to be created an click on Continue afterwards. Page 113

114 3. Setup your GCM Project 1. Click on the Gear icon next to your Project Overview 2. Select Project Settings. In the next screen, select Cloud Messaging. You'll get 2 important values: 1. Legacy Server Key: needs to be entered on the Twixl Distribution Platform. 2. Sender ID: needs to be entered in the build settings in the macos app Page 114

115 ABOUT FIREBASE ANDROID AND IOS APPS: In Firebase, you can setup an Android and/or ios app. This is not necessary for Twixl Publisher issue-based or article-based applications! The only requirement is the setup of a Project (as explained above). 4. Enter API key on Twixl Distribution Platform Page 115

116 Go to the detail view of your app on the Twixl Distribution Platform, then select "Notifications' from the top menu. Now enter the Server API key in the correct field. 5. Enter GCM Sender ID in build setting In the build settings of your app on the macos app (under "Article-based app" or under "App Store Kiosk - Basic Settings"), paste the Sender ID number in the field "Google Cloud Messaging Sender ID". 6. Build your app You have now configured push notifications for Android in your app and are ready to create the build. Page 116

117 Subscriptions Page 117

118 Working with subscriptions for ios 1. Standard subscriptions or all access subscriptions in article-based apps If you want to offer a subscription in an article-based app, there are two options: Standard d Subscription: this is the traditional type of subscription where you get access to new collections (i.e. issues) that are added during the period of your subscription. All Access Subscription: this can be compared to e.g. Spotify or Apple Music type of subscriptions: you get access to all content in the app, as long as your subscription remains valid itunes Shared Secret Go to https: /itunesconnect.apple.com -> Manage your Application -> Select your application -> Manage In App Purchases -> Select 'View or generate a shared secret', then copy and paste it into the itunes Shared Secret field of the Settings Default issue (For standard subscriptions only) Lets you determine whether new subscribers will automatically receive the latest collection added to your app, or whether you are going to manually choose that collection. Page 118

119 2. Free or paid (issue-based apps) WARNING ABOUT FREE SUBSCRIPTIONS: Free Subscriptions are only applicable if your app is a legacy Newsstand app. For new apps the following rules applicable: The app can't be a Newsstand app. The app can't contain free in-app purchases or subscriptions. Also see: Adding your kiosk app to Apple's Newsstand (pre-ios 9 - Legacy) If you want to offer a subscription in a legacy issue-based app, it is going to be either a Free or an Auto- Renewable (paid) subscription. 3. Managing issues Every time you add a new issue/collection, you can decide whether it is part of a subscription or not. In the main Subscriptions overview, there's a list of all the issues/collections that are part of the subscription. Selecting 'Subscription issues' will allow you to: 'Add/Remove issue' from a subscription and 'Set a default issue'. The default issue is the issue that new subscribers will automatically get access to. Page 119

120 3.1. Add/remove e issue This checkbox only defines whether a specific issue is part of the subscription or not. When removing an issue from the list, it will no longer be available as part of the subscription, but the issue itself will not be deleted Set t default issue When the user purchases a new subscription, he/she needs to have access to a first issue. Here you can select which issue the user will be able to download after purchasing the subscription. 4. Adding a duration To create a duration for an auto-renewable subscription, you need to specify the following details: Name The name a user will see in the list of subscriptions on the device. Product identifier A unique reverse-dns for this duration. This product identifier has to be the same as the one entered in itunes Connect / Google Play Developer Console, otherwise the subscription won't work correctly. Duration Page 120

121 The interval of the subscription. On ios, it is either 1 week, 1 month, 2 months, 3 months, 6 months or one year. IMPORTANT NOTE: Although the duration for a free subscription is indefinite, you need to define this and make sure the product identifier matches the one in itunes Connect or Google Play. 5. Adding subscription in itunes Connect WARNING ABOUT FREE SUBSCRIPTIONS: Free Subscriptions are only applicable if your app is a legacy Newsstand app. For new apps are the following rules applicable: The app can't be a Newsstand app. The app can't contain free in-app purchases or subscriptions. Also see: Adding your kiosk app to Apple's Newsstand (pre-ios 9 - Legacy) Go to https: /itunesconnect.apple.com -> Manage Your Application -> Select your application -> Manage In-App Purchases -> Create New Page 121

122 Choose the correct type of subscription (Free or Auto-Renewable) and create a new subscription family or select an existing subscription family. Just like on the Twixl Distribution Platform, you have to add a duration for the subscription. You need to use the same product id(entifier) & matching duration as on the Twixl Distribution Platform, for example com.mycompany.myfirstmagazine.subscription.1month NOTE: A user is entitled to all issues within the subscription for the period he has prepaid. If he cancels his subscription before the renewal, he will still get the issue(s) within the current period. Page 122

123 Working with subscriptions for Android Standard subscriptions or all access subscriptions in article-based apps If you want to offer a subscription in an article-based app, there are two options: Standard d Subscription: this is the traditional type of subscription where you get access to new collections (i.e. issues) that are added during the period of your subscription. All Access Subscription: this can be compared to e.g. Spotify or Apple Music type of subscriptions: you get access to all content in the app, as long as your subscription remains valid. Default issue (For standard subscriptions only) Lets you determine whether new subscribers will automatically receive the latest collection added to your app, or whether you are going to manually choose that collection. Page 123

124 Free or paid (issue-based apps) If you want to offer a subscription in a legacy issue-based app, it is going to be either a Free or an Auto- Renewable (paid) subscription. Managing issues/collections Every time you add a new issue/collection, you can decide whether it is part of a subscription or not. In the main Subscriptions overview, there's a list of all the issues that are part of the subscription. Selecting 'Subscription issues' will allow you to: 'Add/Remove issue' from a subscription and 'Set a default issue'. The default issue is the issue that new subscribers will automatically get access to. Add/remove e issue This checkbox only defines whether a specific issue is part of the subscription or not. When removing an issue from the list, it will no longer be available as part of the subscription, but the issue itself will not be deleted. Set t default issue When the user purchases a new subscription, he/she needs to have access to a first issue. Here you can select which issue the user will be able to download after purchasing the subscription. Page 124

125 Adding a duration To create a duration for an auto-renewable subscription, you need to specify the following details: Name The name a user will see in the list of subscriptions on the device. Product identifier A unique reverse-dns for this duration. This product identifier has to be the same as the one entered in the Google Play Developer Console, otherwise the subscription won't work correctly. Duration The interval of the subscription, weekly, monthly, 3 months, 6 months or one year. Adding subscription in the Google Play Developer Console Go to https: /play.google.com -> navigate to the In-App Products for your app. Create the same subscription with the same product identifier & matching duration as on the Twixl Distribution Platform, for example com.mycompany.myfirstmagazine.subscription.1month Page 125

126 Entitlement Page 126

127 Using the Entitlements ts option Entitlements are a way to allow an external system to determine which content a specific user can have access to. In the world of magazines, this is most frequently used to allow print subscribers to automatically access the digital editions. However, the entitlements solution in Twixl Publisher is flexible enough to implement use cases that go further than just allowing print subscribers to have access to the contents. Here are some other examples of what is possible: Allow a user to register to access extra content After a user has registered, allow him to receive content specifically for him Allow a user to select a region when the app opens and get only the content for that specific region Require a user to enter a license key before he can access the content Require a user to accept a license agreement before he can access the content Define users and groups with access privileges for easy in-house distribution Entitlements influence the list of issues that a user can see, download or purchase in the kiosk. It does not have an influence on the actual content of an issue itself. Prerequisitesequisites To use entitlements in your application, you will need: An App Store kiosk app (on ios and/or Android) An account and an app on the Twixl Distribution Platform How entitlements ts work When you create an application that supports entitlements, there are several steps in the process to get this working. Page 127

128 Build settings in the Twixl Publisher OS X app Enable entitlements in your app build. This is configured in the build settings under App Store Kiosk - Entitlements. You will need to enter the following parameters: Entitlements URL: you'll find this in the Entitlements configuration window on the Twixl Distribution Platform Entitlements URL style: defines how the urls for the Entitlements Server are constructed. For more information, see Entitlements Server URLs. Require on startup: if enabled, you will need to be entitled before you can access the content in the app. In other words, this allows you to create a "restricted access" app. Toolbar Button Title: if you want a button to appear in the toolbar of the App Store Kiosk that can trigger the entitlements signin form, you can enter the title for the button here, e.g. "Already a subscriber?". You will also need to specify an info cell in the App Store Kiosk - User Interface. More information on how to integrate this is available in our article "Customizing the App Store kiosk apps". The web page displayed in the info cell should contain a special hyperlink that triggers the entitlements signin form, or alternatively you could directly trigger the registration from the page: tp-entitlements-signin://self or tp-entitlements-register://self Page 128

129 Twixl Distribution Platform Configuration Print Subscribers (for providing print subscribers free access to digital content - users can still see and purchase the different issues and also purchase a subscription through the App Store) User name & password (for a restriced access app, i.e. without a user name and password, users will not be able to access any content) Users & Groups: define access to your publications based on group access privileges - users belong to a group, publications can be visible in on or more groups. Access Key (can be used for providing extra content to anyone with a valid access key) Sections (allows you to have content for e.g. multiple languages, regions in a single app, but by requiring the users to select a language/region they will only see the content relevant for them) Promo Code: allows readers to redeem a promo code and get an issue for free that normally needs to be purchased Custom Entitlements Server (connect via a web service to an external database - technical documentation available here) Then, you can enter user details manually or use the Twixl Distribution Platform Admin API to automatically add, remove or update entitlement info. Page 129

130 Print t Subscriber example When users open the app, they will see a screen that looks like the one above. When the user then taps the Login As Print Subscriber link, this will trigger the special url tp-entitlements-signin://self, open up a modal dialog and show the output of the signin_form API call of the entitlements server. Note that the user needs to be online for this to work. Page 130

131 In this example, a form is displayed that can be used for login/password authentication, but it s up to the publisher to decide which types of information are requested from the user. Sign in Form What is important is that the form submits its parameters using a GET request and that it includes the hidden form parameter called do which should be set to signin. This is required so that the application can catch this and add extra parameters to this action. <form method="get"> <input type="hidden" name="do" value="signin" /> <input type="text" name=" " /> <input type="password" name="password" /> </form> You can also use a hyperlink to do trigger the signin. You can specify the link as follows: <a href="?do=signin&region=uk">select UK</a> Submit form When the user then submits the form or taps the link, the application will catch the signin request and will add the following extra parameters: Page 131

132 app_id: the unique application identifier of the app (e.g. com.twixlmedia.mymagazine ) app_version: the version number of the application (e.g. 1.0 ) udid: the unique Twixl identifier of the device (e.g. 3efad737b4d845ffa6ddc4d514b279e9 ). Using these parameters, a POST request will be sent to the signin action on the Entitlements Server to verify the data. The signin action should return a JSON dictionary with one key in there called token. This will be used in all subsequent calls to identify the user or device. {"token": " "} If something goes wrong or when e.g. the user is not known, an error should be returned. The output should be: {"error": "Unknown subscriber."} Sign in succeeded/error Depending on the result of the signin action, the app will present a new web page, using either the signin_succeeded or signin_error action on the Entitlements Server. Both actions will receive an extra parameter in the query string: signin_succeeded: token This can be used to show e.g. the subscriber details. signin_error: error This can be used to show an error message to the user explaining why the signin failed. If you don t want to show anything and just close the popup window or provide the user with a button to do so, you can use the following special link: tp-close://self Product Identifiers Every time the application now reloads the contents of the store or when someone wants to purchase an issue, the Twixl Distribution Platform will perform the entitlements API call on the Entitlements Server. It will check which product_identifiers a user is entitled for and will allow free access to these issues if so. Page 132

133 Custom Entitlements ts Server If you prefer to use your own entitlements server instead of using the built-in options, then refer to our separate article. Page 133

134 Integrating entitlements ts in a kiosk infocell This article will show you an example of how you can use entitlements data in the info cell of your App Store kiosk app. The basic idea is that we want to be able to show 3 different info cells, based on different criteria: One view if the user is offline (has no network access) One view if the user is online and not entitled One view if the user is online and entitled Below are the different steps to get this working. 1. Enable entitlements ts in the build settings The first step is to enable entitlements in the build settings of your app. Open the Twixl Publisher application, go to the build settings and select the section called App Store Kiosk Entitlements. You will be presented with the screen below - in this example, we did not enter a Toolbar button title as we will use the info cell for that purpose instead. Page 134

135 2. Add the infocell.html file Once you have configured the Entitlements URL, you will need to add a custom html file for the info cell. To do this, select the App Store Kiosk User Interface panel in the build settings, then click Show WebResources at the bottom. This will take you to the folder containing the web resources for that build setting. In this folder, create a file called infocell.html (case-sensitive). You can also download a sample (place the 3 files in the WebResources folder). Also make sure to set the Info cell height to e.g. 150 px in the build settings. This will create an area with a height of 150 px in which the info cell will be displayed. 3. Run the app The next step is to create an app and run it on our device. You can create an ipad development or ad-hoc build or a Android test build. Install the app on the device and run it. The first time you run the app, you should see a screen that is similar to the one below: As you are not entitled the first time you install the app, you will see that the info cell shows a message that you don t have an entitlement token and offers you to login. We are using the entitlement scenario of "print subscribers" in this case. When you hit the login button, it will trigger the entitlements signin form that allows you to sign in. Page 135

136 Enter your print subscriber credentials and login. The reader app will now refresh the kiosk interface after you are logged in and will also reload the info cell. At that point, the info cell will show you that you are entitled, it will also show the entitlement token and allow you to log out. If you don t have a network connection, the info cell will show that you are offline. Page 136