class Spaceship::Tunes::AppVersion
Represents an editable version of an iTunes Connect Application
This can either be the live or the edit version retrieved via the app rubocop:disable Metrics/ClassLength
Attributes
@return (Spaceship::Tunes::AppStatus
) What's the current status of this app
e.g. Waiting for Review, Ready for Sale, ...
@return (String
) The appType number of this version
@return (Spaceship::Tunes::Application
) A reference to the application
this version is for
@return (Bool)
@return (Bool)
@return (Bool)
@return (Bool)
@return (String
) The copyright information of this app
@return (Hash) A hash representing the description in all languages
@return (Bool) Is that the version that's currently available in the App Store?
@return (Hash) A hash representing the keywords in all languages
@return (Array) Raw access the all available languages. You shouldn't use it probably
@return (Spaceship::Tunes::AppImage
) the structure containing information about the large app icon (1024x1024)
@return (Hash) A hash representing the marketing url in all languages
@return (String
) The platform value of this version.
@return (String
) App Status (e.g. 'readyForSale'). You should use `app_status` instead
@return (Hash) The changelog
@return (Bool) Should the app automatically be released once it's approved?
@return (String
) App Review Information Demo Account Password
@return (String
) App Review Information Demo Account User Name
@return (String
) App Review Information Email Address
App Review Information
@return (String
) App Review Information First Name
@return (String
) App Review Information Last Name
@return (String
) App Review Information Notes
@return (String
) App Review Information Phone Number
@return (Boolean) The checkbox that indiciates if a demo account
is needed. Is set automatically depending on if a user and pass are set
@return (Hash) Represents the screenshots of this app version (read-only)
@return (Hash) A hash representing the support url in all languages
@return (Bool) Does the binary contain a watch binary?
@return (Hash) Represents the trailers of this app version (read-only)
GeoJson
@return (Spaceship::Tunes::TransitAppFile
) the structure containing information about the geo json. Can be nil
@return (String
) The version number of this version
@return (Integer) a unqiue ID for this version generated by iTunes Connect
@return (Spaceship::Tunes::AppImage
) the structure containing information about the large watch icon (1024x1024)
Public Class Methods
Create a new object based on a hash. This is used to create a new object based on the server response.
# File lib/spaceship/tunes/app_version.rb, line 161 def factory(attrs) obj = self.new(attrs) obj.unfold_languages return obj end
@param application (Spaceship::Tunes::Application
) The app this version is for @param app_id (String
) The unique Apple ID of this app @param is_live
(Boolean)
# File lib/spaceship/tunes/app_version.rb, line 171 def find(application, app_id, is_live, platform: nil) # we only support applications raise "We do not support BUNDLE types right now" if application.type == 'BUNDLE' # too bad the "id" field is empty, it forces us to make more requests to the server # these could also be cached attrs = client.app_version(app_id, is_live, platform: platform) return nil unless attrs attrs[:application] = application attrs[:is_live] = is_live return self.factory(attrs) end
Public Instance Methods
Returns an array of all builds that can be sent to review
# File lib/spaceship/tunes/app_version.rb, line 232 def candidate_builds res = client.candidate_builds(self.application.apple_id, self.version_id) builds = [] res.each do |attrs| next unless attrs["type"] == "BUILD" # I don't know if it can be something else. attrs[:apple_id] = self.application.apple_id builds << Tunes::Build.factory(attrs) end return builds end
Call this method to make sure the given languages are available for this app You should call this method before accessing the name, description and other localized values This will create the new language if it's not available yet and do nothing if everything's there Important: Due to a bug you have to fetch the `edit_version` again, as it doesn't get refreshed immediately
# File lib/spaceship/tunes/app_version.rb, line 200 def create_languages(languages) languages = [languages] if languages.kind_of?(String) raise "Please pass an array" unless languages.kind_of? Array copy_from = self.languages.find { |a| a['language'] == 'en-US' } || self.languages.first languages.each do |language| # First, see if it's already available found = self.languages.find do |local| local['language'] == language end next if found new_language = copy_from.clone new_language['language'] = language self.languages << new_language end nil end
# File lib/spaceship/tunes/app_version.rb, line 221 def current_build_number if self.is_live? build_version else if candidate_builds.length > 0 candidate_builds.first.build_version end end end
This method will generate the required keys/values for iTunes Connect to validate the uploaded image
# File lib/spaceship/tunes/app_version.rb, line 322 def generate_image_metadata(image_data, original_file_name) { assetToken: image_data["token"], originalFileName: original_file_name, size: image_data["length"], height: image_data["height"], width: image_data["width"], checksum: image_data["md5"] } end
@!group Promo codes
# File lib/spaceship/tunes/app_version.rb, line 515 def generate_promocodes!(quantity) data = client.generate_app_version_promocodes!( app_id: self.application.apple_id, version_id: self.version_id, quantity: quantity ) Tunes::AppVersionGeneratedPromocodes.factory(data) end
@return (Bool) Is that version currently available in the App Store?
# File lib/spaceship/tunes/app_version.rb, line 188 def is_live? is_live end
# File lib/spaceship/tunes/app_version.rb, line 534 def reject! raise 'Version not rejectable' unless can_reject_version client.reject!(self.application.apple_id, self.version_id) end
# File lib/spaceship/tunes/app_version.rb, line 508 def release! client.release!(self.application.apple_id, self.version_id) end
Push all changes that were made back to iTunes Connect
# File lib/spaceship/tunes/app_version.rb, line 297 def save! client.update_app_version!(application.apple_id, self.version_id, raw_data) end
Select a build to be submitted for Review. You have to pass a build you got from - candidate_builds
Don't forget to call save! after calling this method
# File lib/spaceship/tunes/app_version.rb, line 246 def select_build(build) raw_data.set(['preReleaseBuildVersionString', 'value'], build.build_version) raw_data.set(['preReleaseBuildTrainVersionString'], build.train_version) raw_data.set(['preReleaseBuildUploadDate'], build.upload_date) true end
Private methods
# File lib/spaceship/tunes/app_version.rb, line 309 def setup # Properly parse the AppStatus status = raw_data['status'] @app_status = Tunes::AppStatus.get_from_string(status) setup_large_app_icon setup_watch_app_icon setup_transit_app_file if supports_app_transit? setup_screenshots setup_trailers end
Prefill name, keywords, etc…
# File lib/spaceship/tunes/app_version.rb, line 496 def unfold_languages { keywords: :keywords, description: :description, supportURL: :support_url, marketingURL: :marketing_url, releaseNotes: :release_notes }.each do |json, attribute| instance_variable_set("@#{attribute}".to_sym, LanguageItem.new(json, languages)) end end
Set the age restriction rating Call it like this: v.update_rating({
'CARTOON_FANTASY_VIOLENCE' => 0, 'MATURE_SUGGESTIVE' => 2, 'UNRESTRICTED_WEB_ACCESS' => 0, 'GAMBLING_CONTESTS' => 0
})
Available Values github.com/fastlane/fastlane/blob/master/deliver/Reference.md
# File lib/spaceship/tunes/app_version.rb, line 264 def update_rating(hash) raise "Must be a hash" unless hash.kind_of?(Hash) hash.each do |key, value| to_edit = self.raw_data['ratings']['nonBooleanDescriptors'].find do |current| current['name'].include?(key) end if to_edit to_set = "NONE" if value == 0 to_set = "INFREQUENT_MILD" if value == 1 to_set = "FREQUENT_INTENSE" if value == 2 raise "Invalid value '#{value}' for '#{key}', must be 0-2" unless to_set to_edit['level'] = "ITC.apps.ratings.level.#{to_set}" else # Maybe it's a boolean descriptor? to_edit = self.raw_data['ratings']['booleanDescriptors'].find do |current| current['name'].include?(key) end if to_edit to_set = "NO" to_set = "YES" if value.to_i > 0 to_edit['level'] = "ITC.apps.ratings.level.#{to_set}" else raise "Could not find option '#{key}' in the list of available options" end end end true end
Uploads or removes the transit app file @param icon_path (String
): The path to the geojson file. Use nil to remove it
# File lib/spaceship/tunes/app_version.rb, line 361 def upload_geojson!(geojson_path) unless geojson_path raw_data["transitAppFile"]["value"] = nil @transit_app_file = nil return end upload_file = UploadFile.from_path geojson_path geojson_data = client.upload_geojson(self, upload_file) @transit_app_file = Tunes::TransitAppFile.factory({}) if @transit_app_file.nil? @transit_app_file .url = nil # response.headers['Location'] @transit_app_file.asset_token = geojson_data["token"] @transit_app_file.name = upload_file.file_name @transit_app_file.time_stamp = Time.now.to_i * 1000 # works without but... end
Uploads or removes the large icon @param icon_path (String
): The path to the icon. Use nil to remove it
# File lib/spaceship/tunes/app_version.rb, line 335 def upload_large_icon!(icon_path) unless icon_path @large_app_icon.reset! return end upload_image = UploadFile.from_path icon_path image_data = client.upload_large_icon(self, upload_image) raw_data["largeAppIcon"]["value"] = generate_image_metadata(image_data, upload_image.file_name) end
Uploads or removes a screenshot @param icon_path (String
): The path to the screenshot. Use nil to remove it @param sort_order (Fixnum): The sort_order, from 1 to 5 @param language (String
): The language for this screenshot @param device (string): The device for this screenshot @param is_messages (Bool): True if the screenshot is for iMessage
# File lib/spaceship/tunes/app_version.rb, line 383 def upload_screenshot!(screenshot_path, sort_order, language, device, is_messages) raise "sort_order must be higher than 0" unless sort_order > 0 raise "sort_order must not be > 5" if sort_order > 5 # this will also check both language and device parameters device_lang_screenshots = screenshots_data_for_language_and_device(language, device, is_messages)["value"] existing_sort_orders = device_lang_screenshots.map { |s| s["value"]["sortOrder"] } if screenshot_path # adding / replacing upload_file = UploadFile.from_path screenshot_path screenshot_data = client.upload_screenshot(self, upload_file, device, is_messages) # Since October 2016 we also need to pass the size, height, width and checksum # otherwise iTunes Connect validation will fail at a later point new_screenshot = { "value" => { "assetToken" => screenshot_data["token"], "sortOrder" => sort_order, "originalFileName" => upload_file.file_name, "size" => screenshot_data["length"], "height" => screenshot_data["height"], "width" => screenshot_data["width"], "checksum" => screenshot_data["md5"] } } # We disable "scaling" for this device type / language combination # We only set this, if we actually successfully uploaded a new screenshot # for this device / language combination # if this value is not set, iTC will fallback to another device type for screenshots language_details = raw_data_details.find { |d| d["language"] == language }["displayFamilies"]["value"] device_language_details = language_details.find { |display_family| display_family['name'] == device } scaled_key = is_messages ? "messagesScaled" : "scaled" device_language_details[scaled_key]["value"] = false if existing_sort_orders.include?(sort_order) # replace device_lang_screenshots[existing_sort_orders.index(sort_order)] = new_screenshot else # add device_lang_screenshots << new_screenshot end else # removing raise "cannot remove screenshot with non existing sort_order" unless existing_sort_orders.include?(sort_order) device_lang_screenshots.delete_at(existing_sort_orders.index(sort_order)) end setup_screenshots end
Uploads, removes a trailer video or change its preview image
A preview image for the video is required by ITC and is usually automatically extracted by your browser. This method will either automatically extract it from the video (using `ffmpeg) or allow you to specify it using preview_image_path
. If the preview image is specified, ffmpeg` will ot be used. The image resolution will be checked against expectations (which might be different from the trailer resolution.
It is recommended to extract the preview image using the spaceship related tools in order to ensure the appropriate format and resolution are used.
Note: if the video is already set, the trailer_path
is only used to grab the preview screenshot. Note: to extract its resolution and a screenshot preview, the `ffmpeg` tool will be used
@param icon_path (String
): The path to the screenshot. Use nil to remove it @param sort_order (Fixnum): The sort_order, from 1 to 5 @param language (String
): The language for this screenshot @param device (String
): The device for this screenshot @param timestamp (String
): The optional timestamp of the screenshot to grab
# File lib/spaceship/tunes/app_version.rb, line 448 def upload_trailer!(trailer_path, language, device, timestamp = "05.00", preview_image_path = nil) raise "No app trailer supported for iphone35" if device == 'iphone35' device_lang_trailer = trailer_data_for_language_and_device(language, device, is_messages) if trailer_path # adding / replacing trailer / replacing preview raise "Invalid timestamp #{timestamp}" if (timestamp =~ /^[0-9][0-9].[0-9][0-9]$/).nil? if preview_image_path check_preview_screenshot_resolution(preview_image_path, device) video_preview_path = preview_image_path else # IDEA: optimization, we could avoid fetching the screenshot if the timestamp hasn't changed video_preview_resolution = video_preview_resolution_for(device, trailer_path) video_preview_path = Utilities.grab_video_preview(trailer_path, timestamp, video_preview_resolution) end video_preview_file = UploadFile.from_path video_preview_path video_preview_data = client.upload_trailer_preview(self, video_preview_file) trailer = device_lang_trailer["value"] if trailer.nil? # add trailer upload_file = UploadFile.from_path trailer_path trailer_data = client.upload_trailer(self, upload_file) trailer_data = trailer_data['responses'][0] trailer = { "videoAssetToken" => trailer_data["token"], "descriptionXML" => trailer_data["descriptionDoc"], "contentType" => upload_file.content_type } device_lang_trailer["value"] = trailer end # add / update preview # different format required ts = "00:00:#{timestamp}" ts[8] = ':' trailer.merge!({ "pictureAssetToken" => video_preview_data["token"], "previewFrameTimeCode" => ts.to_s, "isPortrait" => Utilities.portrait?(video_preview_path) }) else # removing trailer raise "cannot remove non existing trailer" if device_lang_trailer["value"].nil? device_lang_trailer["value"] = nil end setup_trailers end
Uploads or removes the watch icon @param icon_path (String
): The path to the icon. Use nil to remove it
# File lib/spaceship/tunes/app_version.rb, line 348 def upload_watch_icon!(icon_path) unless icon_path @watch_app_icon.reset! return end upload_image = UploadFile.from_path icon_path image_data = client.upload_watch_icon(self, upload_image) raw_data["watchAppIcon"]["value"] = generate_image_metadata(image_data, upload_image.file_name) end
@return (String
) An URL to this specific resource. You can enter this URL into your browser
# File lib/spaceship/tunes/app_version.rb, line 302 def url url = "https://itunesconnect.apple.com/WebObjects/iTunesConnect.woa/ra/ng/app/#{application.apple_id}/ios/versioninfo/" url += "deliverable" if self.is_live? return url end
Private Instance Methods
ensure the specified preview screenshot has the expected resolution the specified target device
# File lib/spaceship/tunes/app_version.rb, line 752 def check_preview_screenshot_resolution(preview_screenshot_path, device) is_portrait = Utilities.portrait?(preview_screenshot_path) expected_resolution = TunesClient.video_preview_resolution_for(device, is_portrait) actual_resolution = Utilities.resolution(preview_screenshot_path) orientation = is_portrait ? "portrait" : "landscape" raise "Invalid #{orientation} screenshot resolution for device #{device}. Should be #{expected_resolution}" unless actual_resolution == expected_resolution end
# File lib/spaceship/tunes/app_version.rb, line 572 def container_data_for_language_and_device(data_field, language, device) raise "#{device} isn't a valid device name" unless DeviceType.exists?(device) languages = raw_data_details.select { |d| d["language"] == language } # IDEA: better error for non existing language raise "#{language} isn't an activated language" unless languages.count > 0 lang_details = languages[0] display_families = lang_details["displayFamilies"]["value"] device_details = display_families.find { |display_family| display_family['name'] == device } raise "Unexpected state: missing device details for #{device}" unless device_details.key?(data_field) return device_details[data_field] rescue => ex raise "iTunes Connect error: #{ex}" end
# File lib/spaceship/tunes/app_version.rb, line 760 def raw_data_details raw_data["details"]["value"] end
# File lib/spaceship/tunes/app_version.rb, line 563 def screenshots_data_for_language_and_device(language, device, is_messages) data_field = is_messages ? "messagesScreenshots" : "screenshots" container_data_for_language_and_device(data_field, language, device) end
# File lib/spaceship/tunes/app_version.rb, line 541 def setup_large_app_icon large_app_icon = raw_data["largeAppIcon"]["value"] @large_app_icon = nil @large_app_icon = Tunes::AppImage.factory(large_app_icon) if large_app_icon end
generates the nested data structure to represent screenshots
# File lib/spaceship/tunes/app_version.rb, line 690 def setup_messages_screenshots_for(row) return [] if row.nil? || row["displayFamilies"].nil? display_families = row.fetch("displayFamilies", {}).fetch("value", nil) return [] unless display_families result = [] display_families.each do |display_family| display_family_screenshots = display_family.fetch("messagesScreenshots", {}) next unless display_family_screenshots display_family_screenshots.fetch("value", []).each do |screenshot| screenshot_data = screenshot["value"] data = { device_type: display_family['name'], language: row["language"], is_imessage: true # to identify imessage screenshots later on (e.g: during download) }.merge(screenshot_data) result << Tunes::AppScreenshot.factory(data) end end return result end
# File lib/spaceship/tunes/app_version.rb, line 587 def setup_screenshots @screenshots = {} raw_data_details.each do |row| # Now that's one language right here @screenshots[row['language']] = setup_screenshots_for(row) + setup_messages_screenshots_for(row) end end
generates the nested data structure to represent screenshots
# File lib/spaceship/tunes/app_version.rb, line 597 def setup_screenshots_for(row) return [] if row.nil? || row["displayFamilies"].nil? display_families = row.fetch("displayFamilies", {}).fetch("value", nil) return [] unless display_families result = [] display_families.each do |display_family| # { # "name": "iphone6Plus", # "scaled": { # "value": false, # "isEditable": false, # "isRequired": false, # "errorKeys": null # }, # "screenshots": { # "value": [{ # "value": { # "assetToken": "Purple62/v4/08/0a/04/080a0430-c2cc-2577-f491-9e0a09c58ffe/mzl.pbcpzqyg.jpg", # "sortOrder": 1, # "type": null, # "originalFileName": "ios-414-1.jpg" # }, # "isEditable": true, # "isRequired": false, # "errorKeys": null # }, { # "value": { # "assetToken": "Purple71/v4/de/81/aa/de81aa10-64f6-332e-c974-9ee46adab675/mzl.cshkjvwl.jpg", # "sortOrder": 2, # "type": null, # "originalFileName": "ios-414-2.jpg" # }, # "isEditable": true, # "isRequired": false, # "errorKeys": null # }], # "messagesScaled": { # "value": false, # "isEditable": false, # "isRequired": false, # "errorKeys": null # }, # "messagesScreenshots": { # "value": [{ # "value": { # "assetToken": "Purple62/v4/08/0a/04/080a0430-c2cc-2577-f491-9e0a09c58ffe/mzl.pbcpzqyg.jpg", # "sortOrder": 1, # "type": null, # "originalFileName": "ios-414-1.jpg" # }, # "isEditable": true, # "isRequired": false, # "errorKeys": null # }, { # "value": { # "assetToken": "Purple71/v4/de/81/aa/de81aa10-64f6-332e-c974-9ee46adab675/mzl.cshkjvwl.jpg", # "sortOrder": 2, # "type": null, # "originalFileName": "ios-414-2.jpg" # }, # "isEditable": true, # "isRequired": false, # "errorKeys": null # }], # "isEditable": true, # "isRequired": false, # "errorKeys": null # }, # "trailer": { # "value": null, # "isEditable": true, # "isRequired": false, # "errorKeys": null # } # } display_family.fetch("screenshots", {}).fetch("value", []).each do |screenshot| screenshot_data = screenshot["value"] data = { device_type: display_family['name'], language: row["language"] }.merge(screenshot_data) result << Tunes::AppScreenshot.factory(data) end end return result end
# File lib/spaceship/tunes/app_version.rb, line 715 def setup_trailers @trailers = {} raw_data_details.each do |row| # Now that's one language right here @trailers[row["language"]] = setup_trailers_for(row) end end
generates the nested data structure to represent trailers
# File lib/spaceship/tunes/app_version.rb, line 724 def setup_trailers_for(row) return [] if row.nil? || row["displayFamilies"].nil? display_families = row.fetch("displayFamilies", {}).fetch("value", nil) return [] unless display_families result = [] display_families.each do |display_family| trailer_data = display_family.fetch("trailer", {}).fetch("value") next if trailer_data.nil? data = { device_type: display_family['name'], language: row["language"] }.merge(trailer_data) result << Tunes::AppTrailer.factory(data) end return result end
# File lib/spaceship/tunes/app_version.rb, line 557 def setup_transit_app_file transit_app_file = raw_data["transitAppFile"]["value"] @transit_app_file = nil @transit_app_file = Tunes::TransitAppFile.factory(transit_app_file) if transit_app_file end
# File lib/spaceship/tunes/app_version.rb, line 547 def setup_watch_app_icon watch_app_icon = raw_data["watchAppIcon"]["value"] @watch_app_icon = nil @watch_app_icon = Tunes::AppImage.factory(watch_app_icon) if watch_app_icon end
# File lib/spaceship/tunes/app_version.rb, line 553 def supports_app_transit? raw_data["transitAppFile"] != nil end
# File lib/spaceship/tunes/app_version.rb, line 568 def trailer_data_for_language_and_device(language, device) container_data_for_language_and_device("appTrailers", language, device) end
identify the required resolution for this particular video screenshot
# File lib/spaceship/tunes/app_version.rb, line 746 def video_preview_resolution_for(device, video_path) is_portrait = Utilities.portrait?(video_path) TunesClient.video_preview_resolution_for(device, is_portrait) end