Tutorial 13 - Submitting to the App Store Part 2

    

13.1 Some Runtime Things to Watch

Further to part 1 of this tutorial, there are a couple of things, which if you are not aware of them, can cause problems with running your Codea App in the runtime.

13.1.1 Using Version in the pList

The runtime expects your version variable to be a string. So if you set a version number in Codea using something like saveProjectInfo("Version", version), where version is a number then you will get an error when you try to compile your project.
  
The solution is to either delete this line in your code or to modify a line in the runtime objective C code. If you want to take the second option then in the CodifyAppDelegate class go to the - (NSString) versionForProjectAtPath:(NSString)path method and change the line:
   
NSString* version = [infoPlist objectForKey:@"Version"];
   
To:
   
NSString* version = [[infoPlist objectForKey:@"Version"] description];
   

If you are using a float to represent your version (e.g. 1.4) then it is likely that within the info.plist file (which is found in the Project.codea folder) that this wont be the number you  are expecting (e.g. you get 1.39999999999234 instead of 1.4). This is due to the size of the memory allocated to store numbers in Codea. Anyway, just edit this in your pList file in Xcode back to what it should be. Note that there are two info.plist files, one for your App (found in classes -> Supporting Files) and one for your Codea project.

    

13.1.2 Supporting Orientations

Another trick for young players is that the function orientationChanged(newOrientation) is called before the setup() function in Main. So if you use global variables which are defined in setup() in the orientationChanged() function you will get a runtime error because they haven't been defined yet.

If you are in this situation, the solution is a three step process:

1. In Main, add the following line before anything else:

setupHasRun = false

-- Other global stuff

2. Then in your setup() function, once your setup is done set the variable to true:

  

function setup()
    
    -- setup stuff
  
  setupHasRun = true
      

end

 
3. Finally in the orientationChanged() function:

function orientationChanged(newOrientation)

    if setupHasRun then
        -- Your existing orientation code
    end

end

And that should sort out the problem. Thanks very much to Simeon from Two Lives Left for tracking this solution down.
     

13.2 Customising the Runtime

     

Before submitting your App to iTunes, there are a few things that you will probably want to change in the runtime. We will look at the simple things in this tutorial, a subsequent tutorial will explore how to add things like iAds and Game Centre support.

   

  Figure 1. Changing your Icon & Launch Images in Xcode.

    

13.2.1 App Icons and Launch Images

      

The runtime comes with some default icons and launch images. The easiest way to replace these with your own is to use Xcode.

     

1. Select the Project Navigator (top left button in the tool bar) and click on the top most item in the left pane, called Codea Template.
2. If you then select the summary tab in the right hand (or middle pane depending on how you have Xcode configured) you should see something like Figure 1.
3. Right click (control click) on any of these images and chose "Select File" to change them to your custom versions.
4. There is a plethora of app icon and launch image sizes required, but you can get away with just having these six plus the App store image (which we will get to shortly). The iOS Custom Icon and Image Creation Guidelines lists exactly what dimensions are required and the naming conventions for these images.

           

13.2.2 Hiding the Status Bar

        

Note that you should take into account whether you will be showing the status bar when creating your launch images. Xcode will warn you if the dimensions of your selected images are incorrect. You can hide the status bar by setting the "Status bar is initially hidden" to YES in the info.plist file for your App (found in classes -> Supporting Files).

      

Figure 2. iOS Dev Centre Web Site.

          

13.3 The iOS Dev Centre

            

13.3.1 Provisioning Portal

      

For this next step we are assuming that you already have set up a paid developer account with Apple. The good news is that the App provisioning and certification process has gotten much easier than it was, but it is still a bit tricky so we will step you through the correct order in which things need to happen.

       

Figure 3. iOS Provisioning Portal.

                

1. Open up you favourite browser and go the iOS Dev Centre site (Figure 2). Log in using the Apple ID associated with your Developer Account.
2. Once you are logged in, at the top right of the iOS Dev Centre page is a set of links grouped as "iOS Developer Program". Click on the link which says iOS Provisioning Profile.
3. You should already have a development and distribution certificate. If you haven't, the easiest way to do this is to use the Development Provisioning Assistant. You can start this off by clicking on the button which says "Launch Assistant", it is located in the middle bottom of the page (Figure 3).
4. After you are certified we need to create a new App ID for our App. In the left hand pane of the iOS Provisioning Profile page, click on the link called "App IDs". On the App ID page you will be able to read more than you ever wanted to know about the care and feeding of App ID's. You will also be able to see the status of any App ID's that you currently have in place. Before your eyes glaze over there is one important paragraph buried in there. It starts with "The Bundle Identifier portion of an App ID can be substituted with a wild-card character (asterisk '*') so that a single App ID may be used to build and install multiple applications." We suggest that you don't do this, as wild-card App IDs cannot be used with Push Notifications or for In-App Purchase. 
5. Click on the "New App ID" button in the top right of the screen, and this will take you to the Create a New App ID page shown in Figure 4. Here you have to answer just three questions but the first time you see this, it can be a bit confusing as to what to do. 
6. For description we used "MinesweeperAppID". The description is not important, it is just to remind you which App this ID is for. The next question is important. It is to set the "Bundle Seed ID (App ID Prefix)". We suggest using the default "Use Team ID" as the prefix. As mentioned previously don't use a wildcard "*" for the prefix. The last question is used to set the "Bundle Identifier (App ID Suffix)". This needs to be unique for every App and the usual practice is to use a reverse domain name string. In our case we used "au.com.reefwing.Minesweeper". So what if you don't have a domain? It doesn't matter you just need to use something unique - you could perhaps base it on your name (e.g. "davidsuch.YourAppName"). Click on submit and you will be taken back to the previous App ID status screen where you should now be able to see your shiny new App ID.
7. The last step in this stage is creating our Provisioning Distribution Profile. In the left hand navigation pane click on the "Provisioning" link and then on the Distribution tab. This will show a list of existing Distribution Profiles. Click on the "New Profile" button in the top right. Fill in the details. Distribution method is "App Store", choose an appropriate profile name (we used Minesweeper Distribution Profile), and select the App ID that you just created. Click on "Submit" and you are done.
8. In the top right you will see a link which says "Go to iOS Dev Centre". Click on that and we will be ready for the next stage.

                

Figure 4. Creating a New App ID.

               

13.3.2 iTunes Connect

             

Figure 5. ITunes Connect.

             

Back at the iOS Dev Centre we now want to prepare our App for upload to Apple for review. We do this by using the link below the Provisioning Portal called iTunes Connect. Click on this now. You will probably be asked to sign in again at this stage. 

            

1. On the iTunes Connect page (Figure 5) you will see a link to "Manage Your Applications" at the top of the right hand column. Click on this and then click on the "Add new App" button (top left).
2. You will be asked to select your App type (iOS or Mac OS X). Click on iOS.
3. Enter your App information. This is pretty self explanatory. For SKU we usually use the date (SKU = stock keeping unit, businesses use them to identify a unique product) and make sure that for Bundle ID you select the App ID created in section 13.3.1 above. The App name that you select will also need to be unique - in our case Minesweeper was taken so we went with iMinesweeper instead. When done click "Continue".
4. Next select the availability date and price tier. Use the current (default) date if you want your App released as soon as it is approved by Apple. Select some future date if you want to control the release date. This can be handy if you are co-ordinating a massive marketing effort to drive up demand for your App and its first day sales. Selecting anything else but FREE for the price will bring up a matrix showing the price for that tier in different countries. Click "Continue".
5. Fill out the version information and the age rating survey to determine its rating in the App store (e.g. Minesweeper comes out at a 4+ rating, the lowest possible). Clicking Frequent/Intense for some of these questions will mean that your App can't be sold in selected countries or in some instances at all. Next fill out your App's Metadata, this information will appear in the iTunes App store. The keywords are important because this is how customers will discover your App using the search functionality in iTunes. You are probably okay to go with the standard End User Licence Agreement (EULA), so the last step is to upload the images displayed in the App Store. The large App Icon needs to be 1024x1024 pixels in size. For the iPad screenshots, the easiest way to get these is using Organiser in Xcode (select your iPad from the left hand navigation panel and then screenshots. Run the App on your iPad using Xcode and then click the new screenshot button to take the images you want. You can then export these to a handy folder for upload to iTunes Connect). You can have up to 5 screenshots, drag and drop to change the order. Click "Save" when you are done.
6. After saving your App data you will be brought to the App summary screen. Check that all the details are correct. The status at this stage should be a yellow "Prepare for Upload". Click the "View Details" button below your App icon, then in the top right hand corner, click on "Ready to upload binary".
7. Answer the question about cryptography then click "Save" and then "Continue". Your App status will now be a yellow "Waiting for Upload". Click on App Summary and Done and you should see something like Figure 6, and we need to head back to Xcode for the next step.

            

Figure 6. iTunes Connect - Manage Your Apps.

       

13.3.3 Uploading Your Binary

         

In Xcode, we need to associate our App with the bundle ID that we set up in iTunes Connect. 

1. Before proceeding, we need to download the distribution provisioning profile. In the Organiser window, click on Devices and then Provisioning Profiles in the left hand navigation pane. Click on the Refresh button (bottom left corner) and your new profile will be downloaded.
2. Select the Project Navigator (top left button in the tool bar) and click on the top most item in the left pane, called Codea Template.
3. If you then select the summary tab in the right hand (or middle pane depending on how you have Xcode configured) you should see something like Figure 1. Scroll up to the top of the Summary tab. The Bundle Identifier will currently have: com.twolivesleft.Minesweeper. This needs to be changed to the bundle ID that we established in the steps above. In our case we changed it to au.com.reefwing.Minesweeper. Check that the correct version number is listed while you are here.
4. While we are here we will sign our code with the appropriate distribution profile. Select the "Build Settings" tab and scroll down to the Code Signing section. Under Code Signing Identity -> Release -> Any iOS SDK, select the distribution profile that you just downloaded.
5. Before uploading we need to recompile the binary with all this good stuff included. Select Product -> Archive from the menu bar. After compiling you should see Archive Succeeded in Xcode and the Organiser window will automatically be presented showing your App Archive (Figure 7).
6. In Archives (Figure 7), click on the Validate button (top right) and your archive will be validated prior to upload to Apple. At this stage, you may get an error - "No identities are available for signing." If you do, choose the Connect to iOS Dev Centre, "Download Identities" button. You should now be validated, click on "Finish"
7. Click on Distribute, select submit to the iOS App Store, click "Next" three times and you will see a message "Your application is being uploaded".
8. If all goes well you will get a "Submission Succeeded" message (Figure 8).

          

  Figure 7. Your App Archive in the Organiser Window.

    
Well done if you made it to this point. Believe it or not, Apple have actually streamlined and automated a number of steps in this process which used to be much more cryptic (especially for your first attempt at it).

  
If you want, you can go back into iTunes connect and validate that your App status has changed to orange and "Waiting for Review". In fact, we would recommend that you do this. There have been instances where people have uploaded their binary but for some reason it never moves on to "Waiting for Review." If this happens you can try rejecting the binary and re-uploading it. It will take about a week for the App to work its way up the review queue. Watch this space for updates...

     

Figure 8. Success! You App has been submitted for Review.