How To: Configure the Jive iOS App for Enterprise Distribution

Version 18

    Prerequisites

    • You must have a current iOS Developer Enterprise Program membership in order to get the necessary enterprise distribution certificates from Apple.
    • The person performing the re-signing must have a Mac running the necessary version of Xcode -- currently Xcode 5.

     

    App Customizations

    Some app customizations may be required prior to enterprise distribution.  If you need to customize the app, unzip the .ipa file:

    unzip jive-ios-core.ipa

     

    This will result in a Payload directory containing the directory jive-ios-core.app.  The Payload directory contains the files that can be customized, as described below:

    CustomizationMin iOS App VersionPayload File(s)Value to ModifyDefault ValueNotes
    App Identifier3.0.0Info.plistCFBundleIdentifiercom.jivesoftware.core.enterpriseThe CFBundleIdentifier value must match the app id in the distribution profile you want to use in order for app signing to succeed.  The default app id is com.jivesoftware.core.enterprise.
    App Name3.0.0Info.plistCFBundleDisplayNameJive
    App Icon(s)3.0.0

    icon-57.png

    icon-57@2x.png

    icon-60.png

    icon-60@2x.png

    icon-72.png

    icon-72@2x.png

    icon-76.png

    icon-76@2x.png

    replace all filesicon-57@2x.png

    If any file is not replaced, Jive default icons may show in the Springboard or Spotlight search results.  For more information on app icons, refer to Apple's iOS Human Interface Guidelines: App Icon.

    Allow App to connect to Jive instance that has disabled standard app access3.0.1customer_config.plistallow_public_access => falsetrue

    Requires Jive 6.0.3.2 or later.

    By default, the Jive binary will not connect to a Jive system that has the system property jive.mobile.nativeapp.allowed set to false (see below for system property documentation).  If you have set this system property value in your Jive instance, then you must customize your app so that it will behave differently from the standard version of the app. To do this, in customer_config.plist, set the value of allow_public_access to false.

    Image displayed on login screen3.0.2

    login-logo~iphone.png (122 x 58)

    login-logo@2x~iphone.png (244 x 116)

    login-logo~ipad.png (168 x 80)

    login-logo@2x~ipad.png (336 x 160)

    replace all fileslogin-logo~iphone.png
    Image displayed on settings screen3.0.2

    settings-logo~iphone.png (122 x 58)

    settings-logo@2x~iphone.png (244 x 116)

    settings-logo~ipad.png (168 x 80)

    settings-logo@2x~ipad.png (336 x 160)

    replace all fileslogin-logo~iphone.png
    Image displayed on settings screen3.0.2 - 3.3.3

    sign-in-background~iphone.png (320 × 568)

    sign-in-background~ipad.png (1024 × 1024)

    sign-in-background@2x~iphone.png(640 × 1136)

    sign-in-background@2x~ipad.png(2048 × 2048)

    replace all filessign-in-background~iphone.png
    Image displayed on settings screen3.3.4

    sign-in-background~iphone.png (320 × 568)

    sign-in-background~ipad.png (1024 × 1024)

    sign-in-background@2x~iphone.png(1242 × 2208)

    sign-in-background@2x~ipad.png(2048 × 2048)

    replace all files

    Beginning with 3.3.4 the high end resolution has changed. Note only the 3rd asset has changed from the previous settings:

    sign-in-background@2x~iphone.png(1242 × 2208)

    Default URL in Jive URL field on login page3.0.2customer_config.plistjive_urlnoneSpecify a string value containing the URL to be shown by default in the Jive URL field on the login page.
    Prevent push notification registration3.0.2customer_config.plistallow_push_notification => falsenoneSetting allow_push_notification to false prevents the Jive app from attempting to register for push notifications.  Note that push notifications can also be disabled from the Jive server side from the Admin Console > Mobile > Native Apps tab.  However, disabling push from the server side will not prevent users from seeing the iOS dialog that indicates that app would like to receive push notifications.
    Prevent diagnostic crash reporting from being sent to Jive3.0.2customer_config.plistallow_crash_reporting => falsenoneSetting allow_crash_reporting to false prevents the Jive app from sending app crash logs to Jive.
    OAuth consumer key3.0.2customer_config.plistjive_oauth_consumer_keynone

    It was discussed that some customers may not want to use the Jive for iOS plugin in the addon registry since the OAuth key would be the same across all customers (as the key must be baked into the iOS app in the App Store).

     

    If they created their own plugin in place of the Jive-provided version, they must override the key/secret via customer_config.plist

    OAuth consumer secret3.0.2customer_config.plistjive_oauth_consumer_secretnone(see above)
    OAuth add-on UUID3.0.2customer_config.plistjive_oauth_add_on_uuidnoneIf a customer configured plugin is used in place of the Jive provided version, the UUID of their add-on must go into the customer_config.plist.  The UUID is used to look up whether session grant is enabled for that mobile plugin (permitting logging in via SAML SSO to get a cookie-authed session, then using that cookie to get a OAuth token for use going forward).
    Prevent persistent data cache3.0.2customer_config.plistallow_persistent_data_cache => falsenoneSetting allow_persistent_data_cache to false prevents the Jive app from caching application data retrieved via the API to disk.
    Custom messages for download errors3.0.4customer_config.plist

    download_error_overrides => {

    403: {title: "Custom Title", message: "Custom error message for 403 status code"},

     

    500: {title: ....

    }

    noneThis can contain a dictionary of dictionaries, where the top-level key is the status code of the error message that needs to be replaced, and each inner dictionary contains a "title" field and a "message" field. This addresses a customer request, TABDEV-2944, to have download error messages that better fit their admin settings.
    Google Analytics Key3.0.4customer_config.plistgoogle_analytics_tracking_idnoneThe customer's Google analytics tracking id. This should not be blank if they allow analytics
    Enable or disable Google Analytics3.0.4customer_config.plistallow_google_analyticsenableUsed to disable tracking with google analytics.
    Untrusted Certificate Handling3.2.0customer_config.plistuntrusted_certificate_responsepromptThree options: Prompt, Allow, Reject.  Prompt is the default if this isn't set and will show a popup asking the user if they want to allow access to servers with an untrusted cert.  Allow will allow access without notifying the user.  Reject will not allow access at all.
    Enter instance URL labelJVLoginViewController.strings"cell.title.instanceURL"noneThis is a localized string. Be sure to change all the localized versions.
    Displayable CopyrightJVLoginViewController.strings"copyright.format"noneThis is a localized string. Be sure to change all the localized versions.
    Invalid URL entry alert titleJVLoginViewController.strings"alert.invalidURL.title"noneThis is a localized string. Be sure to change all the localized versions.
    Invalid URL entry alert messageJVLoginViewController.strings"alert.invalidURL.message"noneThis is a localized string. Be sure to change all the localized versions.
    Unsupported Jive Instance alert titleJVLoginViewController.strings"alert.oldInstance.title"noneThis is a localized string. Be sure to change all the localized versions.
    Unsupported Jive Instance alert messageJVLoginViewController.strings"alert.oldInstance.message"noneThis is a localized string. Be sure to change all the localized versions.
    V2 mobile app URL messageJVLoginViewController.strings"alert.jiveMobile.message"noneThis is a localized string. Be sure to change all the localized versions.
    Invalid Instance URL alert titleUIAlertView+JVAdditions.strings"alert.error.title.find"noneThis is a localized string. Be sure to change all the localized versions.
    Invalid Instance URL alert messageUIAlertView+JVAdditions.strings"alert.error.message.find"noneThis is a localized string. Be sure to change all the localized versions.
    Failed to connect to Instance alert titleUIAlertView+JVAdditions.strings"alert.error.title.connect"noneThis is a localized string. Be sure to change all the localized versions.
    Failed to connect to Instance alert messageUIAlertView+JVAdditions.strings"alert.error.message.connect"noneThis is a localized string. Be sure to change all the localized versions.
    Identity ReferenceLabel3.2.1customer_config.plistjive_identity_reference_labelJiveIdentityRefereceLabelThis is the label that was used to store the Identity in the keychain.  Only used if you are using Client Certificate Authentication.
    Keychain Access Group3.2.1jive-ios-core.entitlementsKeychain Access Groups$(AppIdentifierPrefix)com.jivesoftware.core.sharedAccessThis is the access group that the Identity is stored in when using Client Certificate Authentication.  Only modify everything after $(AppIdentifierPrefix).  i.e. $(AppIdentifierPrefix)com.yourcompany.sharedAccess
    A token appended to the UIWebView's "User-Agent" HTTP headers sent during SAML authentication3.3.0customer_config.plistauthentication_user_agent_tokenAny StringThis is useful for providing a unique value in every HTTP request that the SAML identity provider can use to identify that a given HTTP request comes from this app.

    Any other customizations that are possible in the future will be documented here as they become available.

     

    All the localized strings are available for modification. The ones listed above specifically include references to Jive Software that can be changed for branding purposes.

     

    How To: Modify ".strings" in the Jive iOS app Payload (Enterprise Distribution) contains guidance for modifying ".strings" files.

     

    Signing

    If you have made any changes in the .app directory, then be sure to use the .app directory as the target for any further wrapping or signing.  Otherwise, proceed with the provided .ipa.

     

    Before proceeding, we recommend that you test the app with any customizations (e.g., using a developer profile) to ensure that your customizations are working as expected before attempting any other MDM wrapping or integration.  This will isolate help isolate problems with Jive customizations versus problems with the MDM wrapping or enterprise distribution process.

     

    Once you have confirmed that the app is working, you can optionally wrap the binary using the appropriate scripts or tools for your organization.  Please refer to your MDM vendor for assistance with this step; Jive does not provide direct technical support for the app-wrapping or enterprise provisioning process.

     

    Regardless of whether you do any customizations or wrapping, the resulting binary must be signed with the appropriate certificate for your organization's Apple iOS Enterprise program and desired provisioning profile.  Jive cannot sign customized binaries on your behalf, as this would require access to your organization's private keys, and would violate Apple's developer agreements.

     

    Script for re-signing the Jive iOS app binary contains an example script for signing the app using Xcode command-line tools.

     

    If you do not know the signing identity you can use the following command to list them from a terminal window: /usr/bin/security find-identity -v -p codesigning

     

    Once the binary has been signed with the appropriate certificate and provisioning profile, you can distribute the app to your users under the terms of Apple's Enteprise Program.

     

    App Updates

    Updated binaries for the Jive app will be published in Jive Community.  The above steps must be repeated on the new IPA files any time you want to publish an updated app to your users.

     

     

    Jive Community Configurations

    These configurations are performed on the Jive server side and do not need to be repeated when the Jive app binaries are updated, although new configuration options may become available in the future.

     

    Push Notifications

    With the App Store version of the Jive app, push notifications go from Jive installations to Jive's push gateway, and from there to Apple's push servers, using Jive's credentials.  However, for security, Apple requires that only the signer of an app can send push notifications to the app, which means Jive's push gateway cannot send push notification for a custom-signed app.

     

    In order to enable push notifications for your custom-signed Jive app (NOTE: this feature requires Jive Cloud, Jive 7.0.0+, or Jive 6.0.3+ with version 6.1 of the mobile plugin):

    1. Make sure your app is provisioned with an push-enabled certificate and provisioning profile, as described in Apple's Push Notification Programming Guide.
    2. Log in to the Jive Admin Console.  From the Mobile tab, choose Native Apps.
    3. Under Push Notifications, choose Custom.  Under Apple Push Notification Service Certificate, upload your PKCS#12 (.p12) formatted keypair, and provide the corresponding password. (See Apple's provisioning procedure documentation for more information.)
    4. Click Save Changes at the bottom of the page.

    push config.png

     

    Once you have provided the correct credentials, then any Jive Inbox activity will generate push notifications to users who have installed your app and accepted push notifications.

     

    You are not required to enable push notifications for your app.  To disable push notifications for the entire community, log in to the Jive Admin Console. From the Mobile tab, choose Native Apps, and under Push Notifications, choose None.

     

    If push notification are enabled for the community, each app user can also choose to enable, disable, or customize the behavior of push notifications using standard iOS configuration options.  To do this, on the iOS device, launch Settings > Notification Center and then locate your customized Jive app (the name of the app may have been changed) in the list.

     

    Other Jive Settings

    There are several additional Jive system properties you may wish to configure depending on your level of customization.

    Jive System PropertyRequired Jive VersionsMin iOS App VersionsDefault ValueDescription
    jive.mobile.redirect.prompt
    • Jive 6 with Mobile 6.1 plugin
    • Jive 7.0.0+
    • Jive Cloud
    does not depend on app versiontrue on Employee (internal) communities, false on Customer (external)  communities

    When the mobile redirector is enabled (Admin Console > Mobile > General Settings), setting this value to true adds a prompt during redirection on supported iOS devices to either (1) open the link in the browser or (2) launch or install  the Jive iOS app.  If false, no prompt will be displaed; the link will always open directly in the web browser.

    jive.mobile.app.url
    • Jive 6 with Mobile 6.1 plugin
    • Jive 7.0.0+
    • Jive Cloud
    does not depend on app versionApp Store link to Jive  iOS appThis is the link that will be launched if the user chooses the "Install" link from the redirect prompt described above.  If you are using an enterprise distribution and have the redirect prompt enabled, update this system property with the URL your users should use to install your custom Jive app.
    jive.mobile.nativeapp.allowed
    • Jive 6.0.3.2+
    • Jive 7.0.0+
    • Jive Cloud
    3.0.1trueBy setting this to false, you can prevent users from connecting to your community using the App Store version of the Jive app rather than their enterprise-distributed version.  The App Store version of the Jive app will not connect to any community where this value is set to false.