Introduction

This guide shows you how to install and configure the Bazaarvoice Mobile SDK into your iOS app. Please make sure you have all the needed requirements for your application first!

Bazaarvoice supports XCode 8.0 or higher.

📘

If you need to use XCode 7.3, the last supported SDK version is 4.2.4.

Versioning

The Mobile SDK for iOS provides support for Objective-C and Swift programming languages. The SDK is versioned so that we can release new features, bug fixes and improvements without compromising the stability of applications using older versions.

Objective-C

This table summarizes the major version releases. For more information refer to the Mobile SDK for iOS (Objective-C) Github repo.

Swift

Supported

Supported versions continue to receive security and bug fixes, but applications using these versions should be upgraded to the latest version when possible to take advantage of new features. New applications should not use these versions.

Latest

This is newest version. New applications SHOULD use the most recent release of this version.

Identifier for Advertisers (IDFA)

The Identifier for Advertisers (IDFA) is a random device identifier assigned by Apple to a user’s device. The IDFA is used for tracking and identifying a user (without revealing personal information). Advertisers use this to track data so they can deliver customized advertising. In iOS 13 and earlier, the IDFA was available by default with the exception of users who had limited ads personalization in the settings on their iOS devices. With the release of iOS 14, users are required to explicitly give permission in order to use the IDFA. Adding the AppTrackingTransparency permission to your apps adds an ATT alert that asks users to allow access to and use of identifiers like IDFA.

Request App Tracking Transparency authorization

If you are using BVSDK version 8.4.0 and above or BVSwift version and above 1.4.0, To display the App Tracking Transparency authorization request for accessing the IDFA, update your Info.plist to add the NSUserTrackingUsageDescription key with a custom message describing your usage. Here is an example description text

<key>NSUserTrackingUsageDescription</key>  
<string> Your data will be used to provide you a better and personalized ad experience. </string>

The usage description appears in the App Tracking Transparency dialog box

Installing iOS SDKs

We support installation of the Bazaarvoice SDK for iOS with CocoaPods, Carthage, Dynamic Framework, or straight up source code. Choose the solution that best fits your development environment.

CocoaPods

Objective-C

By default, each BV module of the Cocoapods installs the BVCore + BVAnalytics modules.

1. Add the pods for which you have an API key into your Podfile:

   1. # each pod is a subpsec so you only need to add the lines for the component you are installing.  
      pod 'BVSDK/BVAnalytics' #Automatically installed by any of the submodules below 
      pod 'BVSDK/BVCommon'  
      pod 'BVSDK/BVCommonUI'  
      pod 'BVSDK/BVConversations'  
      pod 'BVSDK/BVConversationsStores'  
      pod 'BVSDK/BVConversationsUI'  
      pod 'BVSDK/BVCurations'  
      pod 'BVSDK/BVCurationsUI'  
      pod 'BVSDK/BVNotifications'  
   

2. Run the following command from a terminal:

   $ pod install

3. Open the managed .xcworkspace file to open your project in Xcode.

4. In the future, to update to the latest version of the SDK, just run:

   $ pod update

Swift

By default, each BV module of the Cocoapods installs the BVCore + BVAnalytics modules.

1. Add the pods for which you have an API key into your Podfile:

   1. # each pod is a subpsec so you only need to add the lines for the component you are installing.  
      pod 'BVSwift/BVAnalytics' #Automatically installed by any of the submodules below
      pod 'BVSwift/BVCommon'  
      pod 'BVSwift/BVConversations'  
      pod 'BVSwift/BVCurations'  
      pod 'BVSwift/BVRecommendations'
   

2. Run the following command from a terminal:

   $ pod install

3. Open the managed .xcworkspace file to open your project in Xcode. 5. In the future, to update to the latest version of the SDK, just run:

   $ pod update

Carthage

Objective-C

1. Install the latest version of Carthage.

2. Add the following line to your Cartfile:

   github "bazaarvoice/bv-ios-sdk"

3. Follow the Carthage installation instructions.

4. In the future, to update to the latest version of the SDK, run the following command:

   $ carthage update

Swift

1. Install the latest version of Carthage.

2. Add the following line to your Cartfile:

   github "bazaarvoice/bv-ios-swift-sdk"

3. Follow the Carthage installation instructions.

4. In the future, to update to the latest version of the SDK, run the following command:

   $ carthage update

Dynamic Framework

Objective-C

1. Download the latest BVSDK.framework.zip from our GitHub releases page.

2. Drag BVSDK.framework to the "Embedded Binaries" section of your Xcode project's "General" settings. Make sure to select "Copy items if needed".

3. Head to the "Build Phases" section of your Xcode project settings, and create a new "Run Script Build Phase". Paste the following snippet into the text field:

   bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/BVSDK.framework/integrate-dynamic-framework.sh"

Swift

1. Download the latest BVSwift.framework.zip from our GitHub releases page.

2. Drag BVSwift.framework to the "Embedded Binaries" section of your Xcode project's "General" settings. Make sure to select "Copy items if needed".

3. Head to the "Build Phases" section of your Xcode project settings, and create a new "Run Script Build Phase". Paste the following snippet into the text field:

   bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/BVSwift.framework/integrate-dynamic-framework.sh"

Source Code

Objective-C

1. Clone this repo, or download the latest release from GitHub:

   

2. Copy all the source folders under /BVSDK, except the Support folder, into your project. Make sure to select Copy items if needed.

Swift

1. Clone this repo, or download the latest release from GitHub:

   

2. Copy all the source folders under /BVSWift, except the Support folder, into your project. Make sure to select Copy items if needed. document.getElementById('manualInstallVidSwift').play();

Swift Package Manager

Swift

Add a Package Dependency

We are supporting Swift Package Manager integration for Bazaarvoice’s iOS Swift SDK(BVSwift) from version 1.5.0. To add BVSwift package dependency to your Xcode project, use the GitHub Repository and follow the steps listed below

You can add the Swift Package Manager dependency to your Xcode Project by following any one of the below steps:

1. Select File > Swift Packages > Add Package Dependency and enter BVSwift repository URL

2. You can also select the Project and go to the Swift Packages, click the + button, and enter BVSwift repository URL.

3. You can also navigate to your target’s General pane, and in the “Frameworks, Libraries Embedded Content” section, click the + button, select Add Other, and choose Add Package Dependency.

Configuring the iOS SDKs

Objective-C

Once you have installed the source code for the SDK, you are now ready to initialize the BVSDKManager with your API key(s) and environmen (staging versus production).

1. Select configuration options

The table below will generate a configution file for your SDK. The values you set will generate the necessary script and Mobile SDK intialization code to get you up and running quickly.

Each client application should have its own API key. If you need to generate a new key for Conversations please see Conversations Requesting API Keys.

For all other API keys or if you don't know your client ID, contact Bazaarvoice Support or your implementation team.

📘

Enter your Client ID and at least one API key.

Download your configurations and add them to your assets directory.

Once this is done you may proceed to step 2.

Swift

If you include a configuration file in your project BVManager will parse it and register the various configurations within itself. These configurations can then be picked up by the BVSwift objects directly by calling through the respective BVManager hooks defined mostly in the extensions provided in each of the submodules.
The staging and production files can be generated separately by filling in required values in below tables, specific to the environment.

🚧

In the below JSON, add the required details to generate the configuration files. The details are to be filled to generate files for staging and production as per the requirement. The fields that are irrelevant for the required tasks, can be omitted.

{
    "clientId": "SOME_ID",
    "apiKeyCurations": "SOME_KEY",
    "apiKeyConversations": "SOME_KEY",
    "apiKeyConversationsStores": "SOME_KEY",
    "apiKeyShopperAdvertising": "SOME_KEY",
    "analyticsLocaleIdentifier": "SOME_LOCALE"
}

📘

Enter your Client ID and at least one API key.

Generate your configurations from the JSON format above and add them to your assets directory.

Once this is done you may proceed to step 2.

2. Configure headers/imports

Add the correct import statements so you can reference the Mobile SDK modules you are using.

@import BVSDK;

import BVSDK

import BVSwift

3. Initialize the iOS SDK's Manager

• Objective-C

Initialize the BVSDKManager in your XCode project.

After you have completed the previous steps, insert the following code in AppDelegate#applicationDidFinishLaunchingWithOptions:

Staging

          [BVSDKManager configure:BVConfigurationTypeStaging]; //Configure with Staging API keys

Production

          [BVSDKManager configure:BVConfigurationTypeProd]; //Configure with Prod API keys

• Objective-C with Swift

Initialize the BVSDKManager in your XCode project.

After you have completed the previous steps, insert the following code in AppDelegate#applicationDidFinishLaunchingWithOptions:

Staging

          BVSDKManager.configure(.staging) //Configure with Staging API keys

Production

          BVSDKManager.configure(.prod) //Configure with Prod API keys    

• Swift

BVManager initialises its components internally.

Programatically configuring the BVSDK

• Objective-C

The BVSDKManager can also be configured programatically. This scenario is not typically recommended, however, you can use this method if you need to modify your API keys within the same application session.

NSDictionary\*configDict = @{  
    @" apiKeyConversations" : @" YOUR_API_KEY",  
    @"clientId" : @" YOUR_CLIENT_ID"  
};

[BVSDKManager  
    configureWithConfiguration:configDict  
    configType:BVConfigurationTypeStaging  
];

• Objective-C with Swift

The BVSDKManager can also be configured programatically. This scenario is not typically recommended, however, you can use this method if you need to modify your API keys within the same application session. Configure the BVSDKManager programmatically for the Conversations API like the Swift example below. Call BVSDKManager.configure(...) when you need to update the API key and environment in use.

let configDict = ["clientId": "YOUR_CLIENT_ID",  
                "apiKeyConversations": "YOUR_API_KEY"];  
BVSDKManager.configure(withConfiguration: configDict, configType: .staging)

• Swift

The BVManager can also be configured programatically.

📘

Configurations set programmatically will override anything in the configuration file

var config: BVConversationsConfiguration =
  { () -> BVConversationsConfiguration in
 
    let analyticsConfig: BVAnalyticsConfiguration = .configuration(locale: Locale(identifier: "locale"), configType: .staging(clientId: "clientId"))
 
    return BVConversationsConfiguration.all(
      clientKey: "passkey",
      configType: .staging(clientId: "clientId"),
      analyticsConfig: analyticsConfig)
  }()
//replace "locale", “clientId”, “passkey” placeholders with relevant value

This config variable needs to be passed in all requests.