This project is currently work in progress and used only be a few customers. APIs might not be stable yet and might change without further notice
Trustylib library helps you integrate Trusted Shops Trustmark, Shop Grade, Product Grade and Buyer Protection UI widgets in your iOS apps.
Trustmark widget shows the validity of your trust certificate issued by Trusted Shops.
In case, your trust certificate gets expired, the Trustmark widgets is presented like this,
Shop Grade widget expands to show shop rating and status (Excellent, Good, Fair, etc) with a nice animated effect. The widget however shows the aggregate rating and status only, it doesn't show shop actual reviews' details like review text, review date, attachments, etc.
Buyer Protection widget shows details about shop's buyer protection amount. This widget is available from CocoadPod version 1.1.0+ and Swift Package version 1.1.0+).
Product Grade widget shows product image, rating and status (Excellent, Good, Fair, etc) with an animated user interface. This widget is available from CocoadPod version 1.2.1+ and Swift Package version 1.2.1+).
Trustylib can be added to your iOS projects via both Swift Package Manager and Cocoapods.
Example projects have working integration of the Trustylib library for different iOS technology stacks.
Trustylib library can easily be added to xcode projects via Swift Package Manager. Here is how it is done,
- While xcode project is open, go to
File > Add Packages... > - Enter Trustylib library's git URL (https://github.com/trustedshops-public/etrusted-ios-trustbadge-library.git) in the search box, xcode will display the library details. Please select
Upto next major versionfor the dependancy rule, xcode will automatically fill the latest Trustylib release version number i.e.1.2.6
- Click on
Add packagebutton. Xcode will clone the Trustylib git repository and attach to the xcode project, it should look like this,
- Great! The library is now added to the xcode project and is all good for use.
You need to install Cocoapods first, if not already installed. Cocoapods usase guides have details about installing and using it.
After installation, you need to include Trustylib library as a pod in the podfile,
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'
use_frameworks!
target 'MyApp' do
pod 'Trustylib'
end
And then run pod install command in the terminal,
pod install
You should now have the latest version i.e. 1.2.6 of Trustylib library added to your xcode project!
Trustylib calls TrustedShops backend API for loading details like trust certificate validity, grade/rating, buyer protection, etc. TrustedShops backend API has three environments development, stage and production and Trustylib can be configured to connect to one of these environments for loading your shop and product grade/rating details.
Trustylib looks for a TrustbadgeEnvironment property in your iOS app's info.plist file. If this property is found, Trustylib environment is set accordingly. Else, library's environment is set to production as default environment.
To provide a valid value to the TrustbadgeEnvironment property, you need to add a user defined property (with possible values as development, stage and production) under your xcode project's target build settings. This is how it is done,
Trustylib has one TrustbadgeView view which makes it very easy to present Trustmark, Shop Grade, Product Grade and Buyer Protection widgets. We just need to provide inputs like TSID, channel id, product id and context, based on these inputs TrustbadgeView then presents the required widgets.
This is how, the Trustmark widget is created,
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
context: .trustMark
)These lines of code create the Shop Grade widget,
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .shopGrade
)The Buyer Protection widget can be created with these lines of code,
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .buyerProtection
)This is how, Product Grade widget is added,
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-c0ad29ff-a086-4191-a663-82fed64f6f65",
productId: "31303033",
context: .productGrade
)Product id is needed only for product grade widget and it represents product SKU. For any help realted to product id, please contact Trsuted Shop's CSM via email: [email protected].
Your TSID is generally shared during the onboarding process with Trusted Shops. If in case, you don't have it, please contact Trsuted Shop's CSM via email: [email protected]. You may also contact Trusted Shop's mobile engineering team via email: [email protected]
ChannelId is available in the Trusted Shop's Control Center URL for a shop. For example, in this URL https://app.etrusted.com/etrusted/reviews/inbox?channels=chl-2bf4346e-9897-4e3c-8793-bdbf15c007ae, the channel id is chl-2bf4346e-9897-4e3c-8793-bdbf15c007ae. Here is how it looks in the Control Center URL,
Displaying Trustmark widget in your iOS app is pretty easy after you have added the Trustylib library to your XCode project/s. Here are the code samples for adding widgets for different iOS technology stacks,
Trustylib widgets are created using SwiftUI, hence its pretty straight forward to use them in SwiftUI projects.
import Trustylib
import SwiftUI
struct ContentView: View {
var body: some View {
VStack {
Spacer()
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
context: .trustMark
)
.frame(height: 75)
}
.padding()
}
}Trustylib widgets are created using SwiftUI framework, therefore we need to wrap the Trustbadge widget with UIHostingController so that the widget could be added to the views created with UIKit framework. Here is how it is done,
import UIKit
import SwiftUI
import Trustylib
class RootViewController: UIViewController {
private lazy var trustbadgeView: UIHostingController = {
let trustbadge = TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
context: .trustMark
)
return UIHostingController(rootView: trustbadge)
}()
override func viewDidLoad() {
super.viewDidLoad()
self.addTrustbadgeView()
}
private func addTrustbadgeView() {
self.addChild(self.trustbadgeView)
self.view.addSubview(self.trustbadgeView.view)
/// Setup the constraints to update the SwiftUI view boundaries.
self.trustbadgeView.view.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
self.trustbadgeView.view.centerYAnchor.constraint(equalTo: self.view.centerYAnchor),
self.trustbadgeView.view.leadingAnchor.constraint(equalTo: self.view.leadingAnchor, constant: 16),
self.trustbadgeView.view.trailingAnchor.constraint(equalTo: self.view.trailingAnchor, constant: -16),
self.trustbadgeView.view.heightAnchor.constraint(equalToConstant: 75)
])
}
}Trustylib library has TrustbadgeViewWrapper for adding Trustbadge views to Objective-C code. Below code shows, how it is done,
#import "RootViewControllerObjectiveC.h"
#import <Trustylib/Trustylib-Swift.h>
@interface RootViewControllerObjectiveC ()
@end
@implementation RootViewControllerObjectiveC{
UILabel *label;
}
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
UIViewController *trustbadgeViewController = [
TrustbadgeViewWrapper
createTrustbadgeViewWithTsId:@"X330A2E7D449E31E467D2F53A55DDD070"
context: TrustbadgeContextTrustMark
];
[self addChildViewController: trustbadgeViewController];
[self.view addSubview: trustbadgeViewController.view];
trustbadgeViewController.view.translatesAutoresizingMaskIntoConstraints = NO;
[trustbadgeViewController.view.centerYAnchor constraintEqualToAnchor: self.view.centerYAnchor].active = YES;
[trustbadgeViewController.view.leadingAnchor constraintEqualToAnchor: self.view.leadingAnchor constant: 16].active = YES;
[trustbadgeViewController.view.trailingAnchor constraintEqualToAnchor: self.view.trailingAnchor constant: -16].active = YES;
[trustbadgeViewController.view.heightAnchor constraintEqualToConstant: 75].active = YES;
}
@endTo display the Shop Grade widget, you just need to pass shopGrade context and a valid channel id to the TrustbadgeView in above code examples.
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .shopGrade
)
.frame(height: 75)private lazy var trustbadgeView: UIHostingController = {
let trustbadge = TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .shopGrade
)
return UIHostingController(rootView: trustbadge)
}()
private func addTrustbadgeView() {
self.addChild(self.trustbadgeView)
self.view.addSubview(self.trustbadgeView.view)
/// Setup the constraints to update the SwiftUI view boundaries.
self.trustbadgeView.view.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
self.trustbadgeView.view.centerYAnchor.constraint(equalTo: self.view.centerYAnchor),
self.trustbadgeView.view.leadingAnchor.constraint(equalTo: self.view.leadingAnchor, constant: 16),
self.trustbadgeView.view.trailingAnchor.constraint(equalTo: self.view.trailingAnchor, constant: -16),
self.trustbadgeView.view.heightAnchor.constraint(equalToConstant: 75)
])
}UIViewController *trustbadgeViewController = [
TrustbadgeViewWrapper
createTrustbadgeViewWithTsId:@"X330A2E7D449E31E467D2F53A55DDD070"
channelId:@"chl-b309535d-baa0-40df-a977-0b375379a3cc"
context: TrustbadgeContextShopGrade
];
[self addChildViewController: trustbadgeViewController];
[self.view addSubview: trustbadgeViewController.view];To display the Buyer Protection widget, you just need to pass buyerProtection context to the TrustbadgeView in above code examples.
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .buyerProtection
)
.frame(height: 75)private lazy var trustbadgeView: UIHostingController = {
let trustbadge = TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .buyerProtection
)
return UIHostingController(rootView: trustbadge)
}()
private func addTrustbadgeView() {
self.addChild(self.trustbadgeView)
self.view.addSubview(self.trustbadgeView.view)
/// Setup the constraints to update the SwiftUI view boundaries.
self.trustbadgeView.view.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
self.trustbadgeView.view.centerYAnchor.constraint(equalTo: self.view.centerYAnchor),
self.trustbadgeView.view.leadingAnchor.constraint(equalTo: self.view.leadingAnchor, constant: 16),
self.trustbadgeView.view.trailingAnchor.constraint(equalTo: self.view.trailingAnchor, constant: -16),
self.trustbadgeView.view.heightAnchor.constraint(equalToConstant: 75)
])
}UIViewController *trustbadgeViewController = [
TrustbadgeViewWrapper
createTrustbadgeViewWithTsId:@"X330A2E7D449E31E467D2F53A55DDD070"
channelId:@"chl-b309535d-baa0-40df-a977-0b375379a3cc"
context: TrustbadgeContextBuyerProtection
];
[self addChildViewController: trustbadgeViewController];
[self.view addSubview: trustbadgeViewController.view];This is how, Product Grade widget can be added depending on the iOS technologies stack being used for the app,
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-c0ad29ff-a086-4191-a663-82fed64f6f65",
productId: "31303033",
context: .productGrade
)
.frame(height: 75)private lazy var trustbadgeView: UIHostingController = {
let trustbadge = TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-c0ad29ff-a086-4191-a663-82fed64f6f65",
productId: "31303033",
context: .productGrade
)
return UIHostingController(rootView: trustbadge)
}()
private func addTrustbadgeView() {
self.addChild(self.trustbadgeView)
self.view.addSubview(self.trustbadgeView.view)
/// Setup the constraints to update the SwiftUI view boundaries.
self.trustbadgeView.view.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
self.trustbadgeView.view.centerYAnchor.constraint(equalTo: self.view.centerYAnchor),
self.trustbadgeView.view.leadingAnchor.constraint(equalTo: self.view.leadingAnchor, constant: 16),
self.trustbadgeView.view.trailingAnchor.constraint(equalTo: self.view.trailingAnchor, constant: -16),
self.trustbadgeView.view.heightAnchor.constraint(equalToConstant: 75)
])
}UIViewController *trustbadgeViewController = [
TrustbadgeViewWrapper
createTrustbadgeViewWithTsId:@"X330A2E7D449E31E467D2F53A55DDD070"
channelId:@"chl-c0ad29ff-a086-4191-a663-82fed64f6f65"
productId:@"31303033"
context: TrustbadgeContextProductGrade
];
[self addChildViewController: trustbadgeViewController];
[self.view addSubview: trustbadgeViewController.view];You can set the widget horizontal alignment to leading or trailing to match with your design specifications. This feature is available in CocoadPod version 1.1.0+ and Swift Package version 1.1.0+).
TrustbadgeView has an optional alignment parameter that accepts either .leading or .trailing values. If you don't pass alignment parameter, the widget uses .leading as a default value.
Here is how, you can configure TrustbadgeView with alignment parameter,
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .shopGrade,
alignment: .trailing
)Trustbadge view considers the alignment value for expanding itself towards the correct direction to show widget details. If the alignment is set to .leading, trustbadge content expends towards right whereas for .trailing alignment, content are expended towards left.
Here is how the shop grade widget presents its contents for leading and trailing alignment,
Note: If you are integrating Trustylib in both Android and iOS projects, please note that the badge alignment appears slightly different on these two platforms.
Trustylib library supports dark mode color scheme. It adapts to the iOS system's light and dark color schemes by default. If in case, you need to support only light or dark mode in your iOS apps, the library will adapt to those configurations as well. Dark mode support is available from CocoadPod version 1.2.4+ and Swift Package version 1.2.4+ onwards.
This is how, the library widgets look in dark mode,
To force light or dark color mode for the library so that it doesn't change based on iOS device color scheme, please add below key-value pair to your app's Info.plist file (if not already added)
<key>UIUserInterfaceStyle</key>
<string>Light/Dark</string>UIUserInterfaceStyle key is Apple's recommanded way of sticking to either light or dark mode, thus Trustylib looks for this key in the app's Info.plist file and sets the widgets' color scheme mode based on it's value. If this key isn't found, Trustylib adapts to the iOS system provided dynamic color scheme.
Please let us know if you have suggestions or questions. You may also contact Trusted Shop's mobile engineering team via email: [email protected]