Installation
This guide shows you how to install and import the Bazaarvoice Mobile SDK into your iOS app.
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.
Version | Release Date | Status |
---|---|---|
8.X.X | Oct 12, 2018 | Supported |
8.11.0 | Oct 25, 2023 | Latest |
Swift
Version | Release Date | Status |
---|---|---|
1.X.X | Feb 28, 2020 | Supported |
1.13.2 | Sep 16, 2024 | Latest |
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.
Objective-C
By default, each BV module of the Cocoapods installs the BVCore + BVAnalytics modules.
-
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'
-
Run the following command from a terminal:
$ pod install
-
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
Swift
By default, each BV module of the Cocoapods installs the BVCore + BVAnalytics modules.
-
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'
-
Run the following command from a terminal:
$ pod install
-
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
Objective-C
-
Install the latest version of Carthage.
-
Add the following line to your
Cartfile
:github "bazaarvoice/bv-ios-sdk"
-
Follow the Carthage installation instructions.
-
In the future, to update to the latest version of the SDK, run the following command:
$ carthage update
Swift
-
Install the latest version of Carthage.
-
Add the following line to your
Cartfile
:github "bazaarvoice/bv-ios-swift-sdk"
-
Follow the Carthage installation instructions.
-
In the future, to update to the latest version of the SDK, run the following command:
$ carthage update
Objective-C
-
Download the latest
BVSDK.framework.zip
from our GitHub releases page. -
Drag
BVSDK.framework
to the "Embedded Binaries" section of your Xcode project's "General" settings. Make sure to select "Copy items if needed". -
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
-
Download the latest
BVSwift.framework.zip
from our GitHub releases page. -
Drag
BVSwift.framework
to the "Embedded Binaries" section of your Xcode project's "General" settings. Make sure to select "Copy items if needed". -
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"
Objective-C
-
Clone this repo, or download the latest release from GitHub:
-
Copy all the source folders under
/BVSDK
, except theSupport
folder, into your project. Make sure to select Copy items if needed.
Swift
-
Clone this repo, or download the latest release from GitHub:
-
Copy all the source folders under
/BVSWift
, except theSupport
folder, into your project. Make sure to select Copy items if needed. document.getElementById('manualInstallVidSwift').play();
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:
-
Select File > Swift Packages > Add Package Dependency and enter BVSwift repository URL
-
You can also select the Project and go to the Swift Packages, click the + button, and enter BVSwift repository URL.
-
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).
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.
Products | Production | Staging |
---|---|---|
Curations | ||
Conversations | ||
Conversations for Stores | ||
Product Recommendations & Advertising | ||
Analytics Locale |
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.
Add the correct import statements so you can reference the Mobile SDK modules you are using.
@import BVSDK;
import BVSDK
import BVSwift
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
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
BVManager initialises its components internally.
Programatically configuring the BVSDK
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
];
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)
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.
Updated 3 days ago