TakeMySelfie ios App Documentation

Transcription

1 TakeMySelfie ios App Documentation What is TakeMySelfie ios App? TakeMySelfie App allows a user to take his own picture from front camera. User can apply various photo effects to the front camera. Programmers can also add new effects without caring about user interface which is automatically generated. Features - Live Effects on front camera. The user gets a live preview of his photo with effects. - Easy to add custom effects for programmers. - User can share the photo via Mail, Twitter, Facebook etc. - User can save the photo to his phone. - Minimalist and simple UI. - ios 8 compatible. Version 1.1 changelog - Admob support - Modified UI for changing filters - Changing the camera mode Version 1.01 changelog - ios 8 compatibility Note: The project is updated to work with Xcode 6 and has some additional configuration which may not be read properly in Xocde 5 and may cause some problems. So its strongly recommended that you update your Xcode to version 6. Also screenshots in this document are not updated for Xcode 6 as Xcode 6 has undergone only slight UI changes. All these screenshots of Xcode 5 will still make sense. Anything particular about Xcode 6 is mentioned.

2 Tutorial for personalising TakeMySelfie ios App Requirements 1. A MAC OSX device (Macmini, Macbook Air, Macbook Pro, imac or Mac Pro) 2. Software requirements: Xcode (preferably Xcode 6 for ios 8 compatibility) 3. Technical Requirements: Basic knowledge of programming in Objective C and know how of using Xcode. This involves following steps 1. Install Xcode from AppStore 2. General App Configuration 3. Testing on Simulator 4. Testing on a Real Device* 5. Distributing your app to the App Store* *The last two steps involves a paid ios developer account which has a nominal annual fee. Step 1: Install Xcode from AppStore - Xcode is needed to open, customise and test any ios application source code. It is created by Apple and is a free MAC app. - Click here ( or directly launch the Mac App Store app and search for Xcode. Xcode is about 2-3 GB so it will take some time to download and install it. - Once you have installed Xcode, extract the source code zip and look for the TakeMySelfie.xcworkspace (white coloured icon and not the blue coloured named TakeMySelfie.xcodeproj) file inside TakeMySelfie folder it and open it. It will automatically open in Xcode. Step 2: General App Configuration 2.1 Xcode overview If you re comfortable with Xcode interface the you can jump to 2.2 else read the basics of Xcode by clicking on Help > Xcode overview 2.2 Changing the app name This is important when you want your app to be named something else. e.g. My Custom Selfie App Single click on the name of project at the top of Project Navigator (which is located on the leftmost side). The the project name will be highlighted and you can type the new name. Hit Enter. (Fig 1) Once you hit enter key, under the Activity Viewer, you ll be prompted to change name of some files. (Fig 2 A)

3 Fig 1 Fig 2

4 2.2.3 Uncheck two files named TakeMySelfie-Info.plist and TakeMySelfieTests-Info.plist (Fig 2 B) as we don t want to rename them. Press Rename. If this is first time you re renaming the app then you ll be prompted for Automatic Snapshots (Fig 2 C). Enable them. The selected files will be renamed. When the renaming is complete then screen D (Fig 2 D) appears with green checks for each replacement made and this dialog will auto close after sometime You may test whether your app has been renamed or not by following steps on Section 3: Testing on Device. 2.3 Changing the App Icon The project comes with default set of App Icons and your custom app may need to show your Logo as App Icon Go to the Project Inspector (command+1). In case your Project Inspector doesn t look like in Fig 3 then expose the contents of your project by clicking on the little arrow at the left of your project name. Similarly open TakeMySelfie folder and click Images.xcassets (Fig 3 A). In the panel just right to the Navigator Area (Fig 3 B) all image assets will be listed. Fig In that panel click AppIcon (Fig 3 B). In the Editor View (Fig 3 C) there will be 3 icons for different versions of iphone (retina and non retina display, ios 6 and ios 7) and purposes (App icon, Spotlight icon, Settings icon) ios app icon is square and you should get it designed by some designer or if you have the logo file then you can generate the app icons from online services like In that case your ios AppIcon will look good if your logo is already close to square in shape. Some other ios app generating web services are: All these services will generate icons of different sizes. You will need following sizes in PNG format. 58 x 58px 120 x 120px 80 x 80px 180 x 182px 97 x 97px

5 2.3.5 Once you've obtained icons in these sizes then its time to replace them. Open the folder where you have all icons for sizes mentioned above. Drag and drop on the appropriate tile in the Editor area (Fig 4). Tiles labelled as 1x will have the specified size. e.g. Tile labeled 1x under iphone 29pt will have AppIcon of size 29px. Tiles labelled as 2x will have AppIcon of double the size mentioned. e.g. Tile labelled 2x under iphone 29pt will have image having size 58px (29 x 2). In this case we have all our tiles labelled as 2x, so 29pt means 58px, 40pt means 80px and 60pt means 120px. Keep on doing this till you replace all icons. Fig You can view the changed app icon by following steps on Section 3: Testing on Device. Xcode 6 Note: You ll find an additional 3x variant of these icons and you will have to multiply the dimension with 3 in that case. 2.4 Changing Launch Image Launch Image is an image which shows when your app is loading. Duration depends on your app. but generally for light apps like this it displays for 1-5 seconds. If you don t set a launch image then a black screen is displayed and the user may think that your app is buggy or not functional. Its not a good practice to not have a launch image and of you re submitting your app to app store then its required. Changing a launch image is similar to changing App Icon. The bundle you get has default launch image set. Generally it can be your company logo you used in App Icon and your company name and/or app name Go to the Project Inspector (command+1). In case your Project Inspector doesn t look like in Fig 5 then expose the contents of your project by clicking on the little arrow at the left of your project name. Similarly open TakeMySelfie folder and click Images.xcassets (Fig 5 A). In the panel just right to the Navigator Area (Fig 5 B) all image assets will be listed In that panel click LaunchImage (Fig 5 B). In the Editor View (Fig 5 C) there will be 2 image tiles for different versions of iphone (3.5 inch iphone and 4 inch iphone).

6 2.4.3 ios launch image can be designed using the App Icon if you know to use any image editing software or you should get it designed by some designer. Fig You will need following sizes in PNG format. 640 x 960px 750 x 1334px 640 x 1136px 1242 x 2208px Once you've obtained images in these sizes then its time to replace them. Open the folder where you have all images for sizes mentioned above. Drag and drop on the appropriate tile in the Editor area (Fig 6). Again tiles labelled as 1x will have size 320 x 480px, 2x will have 640 x 960px and R4 stands for Retina 4 which has size 640px x 1136px. In this case we need the latter two You can view the changed launch image by following steps on Section 3: Testing on Device. Xcode 6 Note: You ll find an additional 3x variant of these icons and you will have to multiply the dimension with 3 in that case. Fig 6

7 2.5 Changing bundle ID If you wish to launch your app into app store then you have change the bundle ID of the app. Fig Click on the project icon (Fig 7 A) and on the right side project settings panel will open. Click on the info tab (Fig 7 B). A table will appear below and the second row has the bundle ID under value column (Fig 7 C). Double click to change it and hit command+s to save it Bundle ID is generally web-address-of-your-company-in-reverse-domain-notation + nameof-your-app. e.g. If your web address is and app name is Amazing Selfie App then bundle ID should be com.mobileexceltech.amazing-selfie-app without quotes. There should be no space in the name and each entity is separated by dot. This format is not required and website need not to exist, its just for the purpose of getting a unique ID for your app. If you don t have a company then you can also put your name in bundle ID. e.g. com.jamesanderson.amazing-selfie-app. 2.6 Customising the App behaviour Here we will discuss how to add a new filter to the app. This section is for ios developers only. This applications is configured to use the popular ios library for image manipulation named GPUImage. It has 125 in built filters which you can easily add to your app. Else you have to develop a custom filter and for that you must know basics of Computer Graphics and OPENGL. You can view all filters on GPUImage Github page. As of September 2014 the list of all filters is as follow:

8 Color Adjustments Image Processing Blending modes Visual Effects GPUImageBrightnessFilter GPUImageTransformFilter GPUImageChromaKeyBlendF ilter GPUImageExposureFilter GPUImageCropFilter GPUImageDissolveBlendFilte r GPUImagePixellateFilter GPUImagePolarPixellateFilter GPUImageContrastFilter GPUImageLanczosResamplin gfilter GPUImageMultiplyBlendFilter GPUImagePolkaDotFilter GPUImageSaturationFilter GPUImageSharpenFilter GPUImageAddBlendFilter GPUImageHalftoneFilter GPUImageGammaFilter GPUImageUnsharpMaskFilter GPUImageSubtractBlendFilter GPUImageCrosshatchFilter GPUImageLevelsFilter GPUImageGaussianBlurFilter GPUImageDivideBlendFilter GPUImageSketchFilter GPUImageColorMatrixFilter GPUImageBoxBlurFilter GPUImageOverlayBlendFilter GPUImageThresholdSketchFi lter GPUImageRGBFilter GPUImageSingleComponent GaussianBlurFilter GPUImageDarkenBlendFilter GPUImageToonFilter GPUImageHueFilter GPUImageGaussianSelective BlurFilter GPUImageLightenBlendFilter GPUImageSmoothToonFilter GPUImageToneCurveFilter GPUImageGaussianBlurPositi onfilter GPUImageColorBurnBlendFilt er GPUImageEmbossFilter GPUImageHighlightShadowFi lter GPUImageiOSBlurFilter GPUImageColorDodgeBlendF ilter GPUImagePosterizeFilter GPUImageLookupFilter GPUImageMedianFilter GPUImageScreenBlendFilter GPUImageSwirlFilter GPUImageAmatorkaFilter GPUImageBilateralFilter GPUImageExclusionBlendFilt er GPUImageMissEtikateFilter GPUImageTiltShiftFilter GPUImageDifferenceBlendFilt er GPUImageBulgeDistortionFilt er GPUImagePinchDistortionFilt er GPUImageSoftEleganceFilter GPUImage3x3ConvolutionFilt er GPUImageHardLightBlendFilt er GPUImageStretchDistortionFil ter GPUImageColorInvertFilter GPUImageSobelEdgeDetecti onfilter GPUImageSoftLightBlendFilte r GPUImageSphereRefractionF ilter GPUImageGrayscaleFilter GPUImagePrewittEdgeDetecti onfilter GPUImageAlphaBlendFilter GPUImageGlassSphereFilter GPUImageMonochromeFilter GPUImageThresholdEdgeDet ectionfilter GPUImageSourceOverBlendF ilter GPUImageVignetteFilter GPUImageFalseColorFilter GPUImageCannyEdgeDetecti onfilter GPUImageColorBurnBlendFilt er GPUImageKuwaharaFilter GPUImageHazeFilter GPUImageHarrisCornerDetec tionfilter GPUImageColorDodgeBlendF ilter GPUImageKuwaharaRadius3 Filter GPUImageSepiaFilter GPUImageNobleCornerDetec tionfilter GPUImageNormalBlendFilter GPUImagePerlinNoiseFilter GPUImageOpacityFilter GPUImageShiTomasiCornerD etectionfilter GPUImageColorBlendFilter GPUImageCGAColorspaceFil ter GPUImageSolidColorGenerat or GPUImageNonMaximumSupp ressionfilter GPUImageHueBlendFilter GPUImageMosaicFilter GPUImageLuminanceThresh oldfilter GPUImageXYDerivativeFilter GPUImageSaturationBlendFilt er GPUImageJFAVoronoiFilter GPUImageAdaptiveThreshold Filter GPUImageCrosshairGenerato r GPUImageLuminosityBlendFil ter GPUImageVoronoiConsumer Filter

9 Color Adjustments Image Processing Blending modes Visual Effects GPUImageAverageLuminanc ethresholdfilter GPUImageDilationFilter GPUImageLinearBurnBlendFil ter GPUImageHistogramFilter GPUImageRGBDilationFilter GPUImagePoissonBlendFilter GPUImageHistogramGenerat or GPUImageAverageColor GPUImageLuminosity GPUImageChromaKeyFilter GPUImageErosionFilter GPUImageRGBErosionFilter GPUImageOpeningFilter GPUImageRGBOpeningFilter GPUImageClosingFilter GPUImageMaskFilter GPUImageRGBClosingFilter GPUImageLocalBinaryPattern Filter GPUImageLowPassFilter GPUImageHighPassFilter GPUImageMotionDetector GPUImageHoughTransformLi nedetector GPUImageLineGenerator GPUImageMotionBlurFilter GPUImageZoomBlurFilter To start with adding a filter follow these steps: In the project navigator open Supporting Files folder under TakeMySelfie folder. Click Effects.plist file (Fig 8 A). In the right side you will se the contents of file. Basically its a holds key value pairs Click the root row at the top (Fig 8 B). You ll see a plus icon (Fig 8 C). Click it and a new row will be added at the top (Fig 8 D). Fill the details in key and value columns. Press tab to go to next value. The first value (i.e. the key value) should start with three digit number followed by a hyphen which is followed by the effect name. The second value can be any string with no spaces but it must end with a colon (:). In this case the key is 006-Sketch Effect and value is applyfilter7:. Fig 8

10

11 2.6.3 Go to ViewController.m file. Click the jump bar (Fig 9 A). Click -applyfilter5: in the jump bar to go to that function Filters through 1 to 5 i.e. applyfilter1 to applyfilter5 are single filter and so if you want to add a in built filter from GPUImage then you can use code from any of these filter functions. Copy contents of applyfilter5 (Fig 9 C) and rename the function to the name you gave in the value column in Effects.plist (applyfilter7 in this case, Fig 9 D). Fig Now as you can see in Fig 9 D we have to replace the filter effect and that can be done by replacing the Class name in the return statement (highlighted text in line 149 in Fig 9 D). It can be any name from the table of filters of GPUImage in the start of this section. In this case I have selected GPUImageSketchFilter which converts your image to a sketch version of yours.

12 2.6.6 Hit Save and run the project. You will see the new filter added at the end of filter list by following steps on Section 3: Testing on Device. Step 3: Testing on Device In Xcode we have simulator for testing things out but since this is a camera app and simulator don t have camera so you can t test this app inside a simulator and you have to test it on a real device.

13 For this you need a paid ios developer account (Sign up here: register/index.action). Remember for all the steps mentioned in this section you need an internet connection. Fig 10 B Fig 10 A 3.1 ADDING APPLE ID INTO XCODE (ONE TIME PROCESS) Go to Xcode > Preferences (or hit command+comma key) and click Accounts tab at the top (Fig 10 A) Now a popup will come asking you for your apple ID details. Provide your Apple ID and Password and click Add button (Fig 10 B). After some processing it will add your Apple ID to Xcode and you can view it in the left panel under Accounts tab in Organiser window (Fig 10 C). Fig 10 C

14 3.2 ADD YOUR DEVICE FOR TESTING IN XCODE (ONE TIME PROCESS) Go to your project configuration by clicking the Project icon in Project Navigator (Fig 10 D). Select general tab on the top of right panel and under identity section you ll see a team field which is set to none (Fig 10 E). Select your team from the dropdown (Fig 10 F). Fig 10 D, E, F, G Click the Fix Issue button under the dropdown and Xcode will then do a little processing and add necessary certificates to your Apple Account and also add them to Xcode (Fig 10 G). After sometime the warning of No code signing identity found disappears. Fig 10 H

15 3.2.3 Go to Window > Organiser (or hit shift+command+2) and Organiser window will open. Click devices tab at the top and if you have connected your device to mac device then it will be listed on the left side panel under Devices section (Fig 10 H) If you re testing with this device first time then you ll see a Use for Development button on the right side (Fig 10 H). Click the button A popup will come with a list of Apple Accounts added to Xcode. Select the checkbox on your account name (Fig 10 I) and click Choose (Fig 10 J). Fig 10 I, J 3.3 RUNNING YOUR APP Your device is now ready for testing. Your device must be connected to Mac. In Xcode toolbar select your device in the scheme menu (See Xcode layout at the end of this document). Click Run or hit command + R. Your device must be unlocked for any app to run on your device. 3.4 APP SCREENS Home Screen opens front camera. You can see 3 buttons. Middle one is to click a photo and camera button on left one flips the camera mode to front or back and coloured filter button on right show or hide the filter panel. Filter panel shows a list of filters which you can scroll horizontally by swiping left or right (Fig 11 C). Tap on a filter to activate it. Tap it again to remove it. You can see all in built filters in screens below (Fig 11 D to Fig 11 I) When you take a picture you are directed to another screen where you can: - Download image and save it to your Photo Album (It would ask to access photos in your camera you have allow the app to save the photo). - Retake the photo. Then you ll be sent back to previous screen. - Share the photo via various social channels or via mail.

16 Fig 11 A Fig 11 B Fig 11 C Fig 11 D Fig 11 E Fig 11 F

17 Fig 11 G Fig 11 H Fig 11 J Fig 11 K Fig 11 I

18 Step 5: Distributing your app to the App Store This is done through itunes Connect and Xcode. 5.1 itunes Connect A. Go to itunes Connect ( and log in using your paid ios Developer Account. B. Click on Manage your applications and click on the Add New App button. C. Fill the form and click on continue. (The SKU number is a unique number for Apple to identify your app, you can type whatever you want ex : mycompany2014iphoneappname). D. Then Select an Availability Date. E. If you set the date to the current day, the app will be released as soon as it gets approved. F. Then select your price tier. As an option you can also select specific stores. G. Press on continue. H. Complete this entire form and hit save. You can learn more about each field by hovering each help icon with your mouse. I. Then come back on your app and click on the ready to upload binary button. Your app status should switch to "Waiting for upload. 5.2 Distribute your app from Xcode A. Open your project in xcode. B. In the left menu select your project and go to the info tab. C. Enter the bundle identifier you entered at step C in the ios Dev Center. (Highlighted in red in Fig 17) D. Switch to the Build Settings tab. Click All tab below build settings tab. Change the code signing identity to ios Distribution (Fig 19). E. Click on Product (top bar) and choose archive. F. Once the archiving process is done wait for the organizer window to open. G. Click on validate first and follow each step. Xcode is going to verify the identity and your project settings. H. Once your app passed validation click on Distribute and select submit to the ios App Store. I. Follow each steps and once your app has been uploaded go to itunes connect and check the status of your app. It should be "Upload received". It will switch few minutes after to "Waiting for review". J. The average is usually 5 business days for an app to get approved/rejected. If your app is rejected please contact us at ( to get assistance. Be sure to include as much details as possible (Your project, The resolution center discussion, etc ).

19 Xcode Layout Guide For detailed information, open Xcode, goto Help > Xcode overview.