HOW TO SUBMIT A 4D v12 APP TO THE MAC APP STORE 4D s guidelines for submitting a 4D- created application to Apple s Mac App Store

(1)

HOW TO SUBMIT A 4D v12 APP TO THE MAC APP STORE

4D’s guidelines for submitting a 4D-‐created application to Apple’s Mac App Store

v 3.2 5 October 2011

(2)

I. Prerequisites

1. Adhere to Apple’s prerequisites

 Apps that crash will be rejected

 Apps that exhibit bugs will be rejected

 Apps that do not perform as advertised by the developer will be rejected

 Apps that include undocumented or hidden features inconsistent with the description of the app will be rejected

 Apps that use non-‐public APIs will be rejected

 Apps that are "beta", "demo", "trial", or "test" versions will be rejected

 Apps that duplicate apps already in the App Store may be rejected, particularly if there are many of them

 Apps that are not very useful or do not provide any lasting entertainment value may be rejected

 Apps that are primarily marketing materials or advertisements will be rejected

 Apps that are intended to provide trick or fake functionality that are not clearly marked as such will be rejected

 Apps that encourage excessive consumption of alcohol or illegal substances, or encourage minors to consume alcohol or smoke cigarettes, will be rejected

 Apps that provide incorrect diagnostic or other inaccurate device data will be rejected

 Developers "spamming" the App Store with many versions of similar apps will be removed from the Mac Developer Program

 Apps must be packaged and submitted using Apple's packaging technologies included in Xcode -‐ no third party installers allowed

 Apps must be self-‐contained, single application installation bundles, and cannot install code or resources in shared locations

 Apps that download or install additional code or resources to add functionality or change their primary purpose will be rejected

 Apps that download other standalone apps will be rejected

 Apps that install kexts will be rejected

 Apps that require license keys or implement their own copy protection will be rejected

 Apps that present a license screen at launch will be rejected

 Apps may not use update mechanisms outside of the App Store

 Apps must contain all language support in a single app bundle (single binary multiple language)

 Apps that spawn processes that continue to run after a user has quit the app without user consent will be rejected

 Apps that use deprecated or optionally installed technologies (e.g., Java, Rosetta) will be rejected

 Apps that do not run on the currently shipping OS will be rejected

 Apps that are set to auto-‐launch or to have other code automatically run at startup or login without user consent will be rejected

 Apps that request escalation to root privileges or use setuid attributes will be rejected

 Apps that add their icons to the Dock or leave short cuts on the user desktop will be rejected

 Apps that do not use the appropriate Mac OS X APIs for modifying user data stored by other apps (e.g bookmarks, Address Book or Calendar entries) will be rejected

 Apps that do not comply with the Mac OS X File System documentation will be rejected

According to Apple's recommendations, the application should conform to the following rules:

 Except as Noted below, Unless user has Explicitly Choose to save data in renting alternate year (using a File Save As dialog), "should write your application only to rentals THE FOLLOWING:

o ~ / Library / Application Support / <app-‐identifier> o ~ / Library / <app-‐identifier>

o ~ / Library / Caches / <app-‐identifier>

 WHERE CAN <app-‐identifier> be your application's bundle identify icts name, or your company's name. Thesis strings must match What You Provided Through iTunes Connect for this application.

(4)

 You Should Always use Apple programming interfaces to locate paths thesis

(NSSearchPathForDirectoriesInDomains, for example). For more information, see "Creating Paths and Locating Directories" in Low-‐Level File Management Programming Topics.

 If your application marriages libraries of photos, music, or movies, The May application aussi write to directories THE FOLLOWING:

o ~ / Pictures / <app-‐identifier> o ~ / Music / <app-‐identifier> o ~ / Movies / <app-‐identifier>

 Your Application May to write temporary paths That You ACQUIRE-‐through calls to Apple-‐provided API functions.

 You May Also uses Apple frameworks Such as User Defaults, Calendar Store, and Address Book That implicitly write or modify files thesis Outside of Permitted locations.

2. Have a license for 4D Developer Professional or 4D OEM Desktop v12

Contact your 4D representative

3. Have a Mac Developer account (Cost : $99/year)

Please visit: http://developer.apple.com/programs/mac/

4. Install Apple developer tools

Visit http://developer.apple.com/devcenter/mac/index.action and download the latest versions of:

 XCode

 Application Tools

(5)

(6)

II. Generating certificates

It is imperative that you fill all of the conditions listed in the prerequisites above before purchasing a certificate.

Once you are sure you have filled all of these conditions, please follow the procedure that follows:

1. Generate a "Certificate Signing Request" (CSR) from your Mac

- Launch the Keychain application in the /Applications/Utilities folder

- Go to the Keychain menu and click on Keychain Access

- In the Keychain Access drop-‐down menu, select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority

- Fill in the three fields

- In the “Request is” group, select the “Saved to disk” option

- Click “Continue with Keychain Access” to complete the CSR generation process

2. Generate "Mac App Software" certificate

- Go to the Apple site "Developer Certificate Utility":

https://developer.apple.com/certificates/index.action

- Click on the "Create Certificates" link

- Check the two options:

o Mac App Software Certificate o Mac Installer Package Certificate

- Click on "Create Certificate" then Continue

- Click on "Submit" and select "Certificate Signing Request" on your disk

- Click on "Generate" then Continue

- Click on "Download" download the certificate to disk

- Double-‐click on the certificate to install it

- Click on "Continue"

3. Generate the "Mac Installer Package" certificate

- Click on "Create Certificate" then Continue

- Click on "Submit" and select "Certificate Signing Request" on your disk

- Click on "Generate" then Continue

- Click on "Download" download the certificate to disk

- Double-‐click on the certificate to install it

- Click on "Done"

(7)

(8)

III. Preparing the 4D Volume Desktop v12 application

 Copy the "_MASReceipt" folder into the 4D Volume Desktop package’s Content folder.

 Modify info.plist: Add the item "DatabaseOutsidePackage" and assign it the value "true" in lowercase.

IV. Preparing your 4D v12 application

 In the database properties, modify the path of the temporary folder to adhere to Apple’s requirements: Check the option "Data File Folder" in the "Database" tab.

Important: Only on the Mac and only if the key "DatabaseOutsidePackage" is present in the info.plist of an engined database: The placement of the application preferences should be ~/Library/Application Support instead of ~/Library/Preferences. This also cocerns the "System folder" command with the selector "User Preferences_User".

 Copy the "App Store Tools" plug-‐in provided by 4D into your database’s Plugins directory

 This plug-‐in verifies that the certificate sent by Apple is valid, as well as restricting access to your application. While it is not mandatory, it provides a copy protection scheme that is valid by Apple’s standards. (Note: As per the prerequisites above, apps cannot have their own copy protection scheme.)

 Open your database with 4D v12

 Create a new method and enter the 4D code below :

C_TEXT($B_identifer;$B_version;$R_identifier;$R_version;$R_hash;$R_opaque;$GUID;$computed_hash)

//code 173 is recognized by OS X 10.6.6 or later,

//The system interprets the exit status and attempts to obtain a valid receipt.

//Assuming your application signing certificate is valid, the system installs a valid receipt for the application. The system may prompt you for your iTunes credentials.

If (False)

//The application will quit immediately; be sure you know what you are doing! EXIT 173

End if

//These values are read from the application's Info.plist.

//The purpose is to compare againsy the values recorded in the Apple receipt.

$B_identifer:=BUNDLE Get identifer

$B_version:=BUNDLE Get version

//When an application is installed from the App Store, it contains a receipt that is cryptographically signed.

//The receipt is stored inside the application bundle. For example, if your application is named SampleApp, your receipt is located at:

//.../SampleApp.app/Contents/_MASReceipt/receipt

//You can find a copy in the Resources folder of this sample database.

//Fetch the following values from the receipt.

//hash and opaque are raw binary values, converted to hexaecimal.

(9)

$R_version:=RECEIPT Get version

$R_hash:=RECEIPT Get hash

$R_opaque:=RECEIPT Get opaque

//If identifier and version don't match, don't even care about hash, the receipt doesn't match. If ($B_version=$R_version)

If ($B_identifer=$R_identifier)

End if End if

//This is the computer's unique number.

$GUID:=GUID Get identifier

//Pass the computer's GUID, the key from the receipt and the application's UTI. //The values below are from the Apple sample receipt.

$computed_hash:=GUID Compute hash ("0017f2c4bcc0";$R_opaque;$R_identifier)

If (($computed_hash=$R_hash) & (Length($computed_hash)>0))

//The receipt is valid.

//ALERT("OK") Else

ALERT("KO")

End if

 This method can be modified by the developer to manage:

o The version number of the application and that of 4D (BUNDLE Get Version) to manage automatic application updates via the App Store (is the developer based on his/her own version number or on 4D’s, for example)

 The developer should also take care to verify that the application has launched with the "App Store Tools" plug-‐ins present to avoid unauthorized use of the application. You can imagine, for example, generating an MD5 from Miyako’s plug-‐in (available at:

http://sources.4d.com/trac/4d_keisuke/wiki/MacAppStoreTool), storing it in a variable, and comparing it at every launch if the MD5 (a hash allowing the calculation of the plug-‐in’s memory imprint) is still identical. This process allows you to verify that the plug-‐in has not been modified, as well as to avoid users who employ a stub of the plug-‐in, for example. For this, you can use th 4D Pack v12 plug-‐in:

C_TEXT ($ledoc)

C_TEXT (<>digest)

C_LONGINT ($resfork)

$resfork:=0

$ledoc:=Select document

$erreur:=AP Get file MD5 digest ($ledoc;<>digest;$resfork)

Once these modifications have been performed it will be possible to verify that the application is running correctly in its interpreted version. To do so, all you need to do is copy the "_MASReceipt" folder into 4D’s "Contents" folder.

If all is working correctly, we can now complete the generation of an executable.

(10)

V. Submitting your application to the Mac App Store

1. Generate a 4D executable

 Go to Design mode

 From the Design menu, click on "Build Application"

 In the "Application" tab:

 Check the option "Build Stand-‐alone Application"

 Click on the "…" button and select 4D Volume Desktop v12

 In the "Licenses" tab:

 Click on the + button and select your 4D v12 development license starting with 4DDP120 or 4DOE120

 Click on the + button and select your 4D v12 deployment license starting with 4UOE120

 Give your application a name ("Application name" field)

 Select a destination folder

 Click on the "Save" button then "Build"

 Once the application is generated:

 Edit the info.plist :

o specify a build number identical to the "Bundle versions string, short" and "Bundle version" (ex : 1.0)

o specify the name of your app in the "Bundle name" item

 Create a "UserData" folder inside the "Contents" folder, and if you are furnishing data with the build, copy the "4DD" and "match" files there.

 Open Terminal and execute the following line on the app’s executable: o sudo chmod 755 path_of_the_build’s_executable

o Ex: sudo chmod 755 /…/Build/Theater.app/Contents/MacOS/Theater

 Open the executable once to create a blank data file in the package’s "Contents/UserData" folder if you want to avoid the subsequent dialog box (see Apple’s prerequisites).

Note: Apple does not allow the modification of files contained in the package (see Chapter I-‐1, Adhere to Apple’s Prerequisites).

Below is a list of various cases and possible issues :

1st case: Data not provided with the build upon first installation of the application

Upon launching the build:

 Dialog to open data file

o Create a new data file or select an existing one, in either case it should be outside of the package

 Creation of a folder with the name of the build ~Library/Application Support/ o Creating a subfolder with the number of the build

 Copy of the build’s Database folder in this subfolder

o Creating a "startup.4dlink" file containing a path to the structure and the data o Creating a "UserData" folder

2nd _{case: Data provided with the build at the time of first installation of the application}

Upon launching the build:

 No open data

 Creation of a folder with the name of the build in ~Library/Application Support/ o Creation of a subfolder with the number of the build

 Copy of the build’s Database folder in this subfolder

o Creating a "startup.4dlink" file containing a path to the structure and the data o Creating a "UserData" folder

 Copy the 4DD and "match" files into this folder

(11)

3rd case: Data not provided with the biuld when updating the application

Note: An update = a modification of the build’s info.plist, a change to the values of "Bundle versions string, short" and "Bundle version" (1.0 -‐> 1.1, for example)

Upon launching a new build :

 Creating a subfolder with the new build number (e.g. 1.1) in ~Library/Application Support/ o Copy of this build’s Database folder in this subfolder

 Modification of the file "startup.4dlink": The path to the 4DC has been updated

4th case: Data provided with the build when updating the application

Note: An update = a modification of the build’s info.plist, a change to the values of "Bundle versions string, short" and "Bundle version" (1.0 -‐> 1.1, for example)

Upon launching a new build :

 Creating a subfolder with the new build number (e.g. 1.1) in ~Library/Application Support/ o Copy of this build’s Database folder in this subfolder

 Modification of the file "startup.4dlink": The path to the 4DC has been updated

Remark: If the developer requires users to use the data provided with the package when updated, it should be managed programmatically by 4D (copy of the data and match outside of the package, modification of the 4Dlink file, and opening the desired data by using the correct 4D command).

2. Delete the executable’s PPC dode

- Download the free utility TrimTheFat from this address:

http://homepage.mac.com/gweston/macware/TrimTheFat.zip

- Drag and drop your executable on the utility

The utility will automatically rename the old executable. The new executable is thus the one with the right name.

3. Sign your 4D executable

- Launch the Terminal application and copy/paste each of the command lines below, taking care to replace the text "xxxxxxx" with the name used in the two certificates (see Keychain):

o

cd [folder containing the .app]

o

codesign –f –s “3rd Party Mac Developer Application: xxxxxxx” [name of your

application].app

4. Generate and sign your package

-

While still in the same Terminal window, copy /paste the command line below, being careful to replace the bracketed text and the "xxxxxxx" with the name uside in the two certificates (see Keychain):

o

productbuild –component [name of your application].app/Applications –sign “3rd

Party Mac Developer Installer: xxxxxxx” –product [name of your

application].app/Contents/Info.plist [name of your application].pkg

(12)

5. Install your package in the Applications folder

- Delete your .app application if you’d like to test the installation on your own machine or copy the package on another machine.

- Launch Terminal and copy/paste the command line below, being careful to replace the text in brackets with your app name:

o

sudo installer –store –pkg [name of your application].pkg

–target /

Your application is now installed in the Applications folder.

(13)

VI. Submit the application to Apple

1. iTunes Connect

Visit the iTunes Connect site: https://itunesconnect.apple.com/

Create an iTunes Connect account and sign in.

Click on the "Manage Your Applications" link.

(14)

Click on the "Add New App" button.

Fill in the fields and click "Continue".

Select the availability date and price tier for your app.

Tip: To test your submission, select a date very far into the future.

(15)

Fill in the various fields regarding your app’s metadata and click on the "Save" and then "Done" buttons.

Your app’s information will by now be recorded by Apple

Your app’s current status is now "Prepare for Upload."

(16)

Important: You should now expect an email like the one below notifying you that the status of your application has gone to "Waiting for Upload" before continuing to the next step.

2. Installing Application Loader

You can install and run Application Loader on the Mac OS X operating system. If you have installed iOS SDK 3.2 or later, you can access Application Loader from the Utilities folder

(/Developer/Applications/Utilities/Application Loader.app). You can also download Application Loader from iTunes Connect.

To install Application Loader on Mac OS X from iTunes Connect :

 Click the Download Application Loader link

(http://itunesconnect.apple.com/apploader/ApplicationLoad-‐ er_1.3.dmg) in the iTunes Connect Manage Your Applications page (http://www.apple.com/itunes/go/itunesconnect/manageApps).

 iTunes Connect downloads the self-‐extracting installation package (ApplicationLoader_1.3.dmg).

 Double-‐click the installation package (ApplicationLoader.pkg) and follow the instructions that appear.

Note: When installing Application Loader on the Mac, before you can install the software, you must log in to your computer as a member of the administrator group.

(17)

 Read the installation introduction, and then click Continue.

Read the Software License Agreement, and then click Continue and Agree.

 Click Install to perform the standard installation.

 The installation package installs files in your /Developer/Applications/Utilities folder.

 Type your administrator password and click OK, if prompted.

 Click Close.

 Open the Application Loader application by double-‐clicking the Application Loader.app icon in the /Developer/Applications/Utilities folder, or the folder you specified during a custom install. You are now ready to begin using Application Loader.

(18)

3. Starting Application Loader

Before you can use Application Loader to add applications to the App Store, you must initialize Application Loader by providing your iTunes Connect login information at startup.

Double-‐click the Application Loader.app icon in the /Developer/Applications/Utilities folder.

Application Loader opens the Setup Wizard.

 Click Next in the “Welcome to Application Loader” window.

 Type your iTunes Connect login information (Apple ID and password), and then click Next.

Application Loader verifies your iTunes Connect login information and stores your Apple ID and password for future Application Loader operations.

Initializing Application Loader with your iTunes Connect login information is account-‐specific. If you share your machine with other users with different iTunes Connect login information, you can each have your own Apple ID and password setting for Application Loader.

 Click Done.

Application Loader displays the “Choose an application” window so you can begin using Application Loader.

Note: If you change your iTunes Connect password, you must use the Setup Wizard to reset your Apple ID and password in Application Loader. To reset your Apple ID and password, choose Window > Run Setup Wizard in Application Loader, and then repeat steps 2 through 5 above.

(19)

4. Delivering your application

When you have finished uploading your assets and completed the application submission process in iTunes Connect, and your application is in the “Waiting for Upload” state, you can deliver your application binary files to the App Store.

This section describes how to submit your application binary files to the App Store.

When the status of your application in iTunes Connect is “Waiting for Upload”, you can use Application Loader to submit your binary files to the App Store.

To submit your application:

 Choose the name of your application from the Choose pop-‐up menu.

Your application appears in the Choose pop-‐up menu when the application status in iTunes Connect is “Waiting for Upload”. If you have uploaded your metadata and artwork into iTunes Connect but have not yet uploaded your binary, or if your application has been rejected, you will have eligible applications to upload.

 Click Next.

Application Loader searches for all eligible applications which are ready to be added to the App Store, and then displays a Please Confirm window.

 Click Yes to indicate you have tested and qualified your application.

Application Loader displays a window with your application details, including name version number, device support, SKU number, primary language, and copyright.

(20)

 Click Choose, select your application file, and then click Open.

 Click the ellipsis button to replace the current file before to submitting.

 Click Send.

Application Loader begins submitting your application binary file to the App Store.

Click Cancel to stop the upload and close the window. Click Abort to stop the transfer and keep the window open to select another file to submit.

 Click Done.

Use the Manage Your Applications page in iTunes Connect to view the status of your application.

Choose Window > Background Activity to display the Background Activity window and view delivery status information for all applications, including pending messages, time remaining, warning and error messages, and so on.

(21)

Appendix: How to personalize a 4D application

These different steps should be followed just before generating an engined application.

1. Personalizing the About

Create a method "About_ApplicationName" and copy the code below:

C_LONGINT($Lon_windowID)

$Lon_windowID:=Open form window("About_Theater";1984;Horizontally Centered;Vertically Centered)

DIALOG("About_Theater")

CLOSE WINDOW

 In the "On startup" database method, add the following line of code:

SET ABOUT("About Theater";"About_Theater")

2. Removing the help files of any 4D component you may have used

To remove a Help menu item for a component, follow his procedure:

Ex: Remove the menu item "Help for 4D SVG" from the Help menu

 View the component’s package contents

 Delete the help file

 In this example, the file is found at: 4D Volume Desktop.app/Contents/Components/4D SVG.4dbase/4D SVG.htm

3. Adding a Help menu

4D allows you to associate a personalized online help file in order to provide users additional information on using your application.

On the Mac, 4D accepts help files in CHM format. This format is used by all web browsers. Online help is thus displayed in the browser.

Furthermore, you can associate a specific page of the help file to each form in the database, which allows you to provide contextual online help.

Once your online help file has been genrated, you can associate it to a database in such a way that it is automatically called if the user activates online help while working in the database. To do so :

 The file name has to be identical to that of the database structure file. It absolutely must carry the .HTM file extension.

 The help file should be placed next to the structure file or in the "Plugins" folder which is on the same level as the database structure file.

A similar mechanism has been put in place to allow developers to add online help to their components. The principle is similar to that for 4D databases (see : Appendix A: personalized online help):

(22)

 The help file should be placed next to the component’s structure file and have the same file name as the structure.

 Help is thus automatically loaded in the application’s Help menu, "Help for…" followed by the help file name.

4. Personalizing the BuildApp.xml file

 To personalize the application icon, place your ICNS file in the "Resources" folder inside the "Contents" folder.

 Copy the "BuildApp.xml" file in another folder or rename it.

 Edit this copy of BuildApp.xml and add the XML key "RuntimeVLIconMacPath" (/Preferences4D/BuildApp/SourcesFiles/RuntimeVL/RuntimeVLIconMacPath)

 Ex: <RuntimeVLIconMacPath>application.icns</RuntimeVLIconMacPath>

 To modify the copyright of your appliction, add the XML keys "CommonCopyright" and "RuntimeVLCopyright" (/Preferences4D/BuildApp)

 Example:

<CommonCopyright>Company Copyright</CommonCopyright> <CommonCreator>APPL</CommonCreator>

</Common> <RuntimeVL>

<RuntimeVLCopyright>Company Copyright</RuntimeVLCopyright> <RuntimeVLCreator>APPL</RuntimeVLCreator>

</RuntimeVL> </Versioning>

Important: Once you’ve personalized BuildApp.xml, you shouldn’t generate an application from the App Builder dialogue but with the BUILD APPLICATION command.

5. Personalizing the menu bar

 Edit menu:

o Add an "Edit" menu to the menu bar associated with your application

 Mode menu:

o The "Mode" menu has no use in an engined application. If it is present, remove it from your toolbar.

 Quit without verification:

o Create an object method containing the command QUIT 4D.

o Associate this method to the menu item "Quit" in the 4D tool box by leaving the standard "Quit" action.

Note: The standard "Quit" action allows you to place the "Quit" action in the appliction menu. The object method allows you to hide the confirmation dialog to quit. It is thus necessary to use these two mechanisms on the same menu item on the Mac.

(23)

6. Hide the splash screen

The option to hide the splash screen in app preferences doesn’t work for engined applications.

Here is a workaround:

 Create an object method "splash_screen" and copy the code below:

C_LONGINT($nb_win;$cpt)

WINDOW LIST($tabWin)

$nb_win:=Size of array($tabWin)

If ($nb_win>0)

For ($cpt;1;$nb_win)

If (Get window title($tabWin{$cpt})="Application")

<>refWelcomeWin:=$tabWin{$cpt}

$cpt:=$nb_win+1

End if End for End if

 Edit one of the object methods executed at application launch and copy the following code:

splash_screen

If (<>refWelcomeWin>0)

HIDE WINDOW(<>refWelcomeWin)

(24)

4D SAS

Worldwide Headquarters

60, rue d’Alsace -‐ 92110 Clichy -‐ France Tel: +33 1 40 87 92 84 -‐ Fax : +33 1 40 87 92 01

[email protected] -‐ www.4D.com 4D SAS

France +33 1 40 87 92 00

info-‐[email protected]

4D, Inc USA & Canada +1 800 785 3303

[email protected]

4D Deutschland GmbH Germany & Austria

+49 8165 95 19 0 info-‐[email protected]

4D Japan Japan +81 3 5433 3461 info-‐[email protected]

4D UK Ltd United Kingdom +44 1625 536 178

info-‐[email protected]

4D Hispano Spain, Portugal & Latin America

+34 91 414 92 90 info-‐[email protected] info-‐[email protected] info-‐[email protected]

4D Sweden Sweden & Denmark

+46 8 750 63 00 info-‐[email protected]

4D Australasia Australia & New Zealand

+61 2 9499 9544 info-‐[email protected]

(25)

Copyright 2010-‐2011 4D SAS. All rights reserved. 4D and related logos are registered trademarks of 4D SAS. All other quoted trademarks and products names are trademarks and/or registered trademarks of their respective owners.

HOW TO SUBMIT A 4D v12 APP TO THE MAC APP STORE 4D s guidelines for submitting a 4D- created application to Apple s Mac App Store