Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/trustedshops-public/etrusted-ios-trustbadge-library
Show TrustBadge on your iOS app
https://github.com/trustedshops-public/etrusted-ios-trustbadge-library
etrusted trustbadge trustedshops trustedshops-sdk trustylib tslibraries
Last synced: 1 day ago
JSON representation
Show TrustBadge on your iOS app
- Host: GitHub
- URL: https://github.com/trustedshops-public/etrusted-ios-trustbadge-library
- Owner: trustedshops-public
- License: mit
- Created: 2022-11-02T10:38:24.000Z (about 2 years ago)
- Default Branch: develop
- Last Pushed: 2024-12-01T15:01:32.000Z (21 days ago)
- Last Synced: 2024-12-01T16:19:02.954Z (21 days ago)
- Topics: etrusted, trustbadge, trustedshops, trustedshops-sdk, trustylib, tslibraries
- Language: Swift
- Homepage:
- Size: 10.5 MB
- Stars: 2
- Watchers: 2
- Forks: 2
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Contributing: Docs/CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Trusted shops library for the iOS platform #
[](https://github.com/trustedshops-public/etrusted-ios-trustbadge-library/blob/main/LICENSE)
[](https://codecov.io/gh/trustedshops-public/etrusted-ios-trustbadge-library)
[](https://dl.circleci.com/status-badge/redirect/gh/trustedshops-public/etrusted-ios-trustbadge-library/tree/develop)
[](https://sonarcloud.io/summary/new_code?id=trustedshops-public_etrusted-ios-trustbadge-library)
> 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+`).
## 1. Installation ##
Trustylib can be added to your iOS projects via both [Swift Package Manager](https://www.swift.org/package-manager/) and [Cocoapods](https://cocoapods.org/).
[Example projects](https://github.com/trustedshops-public/etrusted-ios-trustbadge-library/tree/main/Example) have working integration of the Trustylib library for different iOS technology stacks.
#### *Swift Package Manager*
Trustylib library can easily be added to xcode projects via Swift Package Manager. Here is how it is done,
1. While xcode project is open, go to `File > Add Packages... >`
2. 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 version` for the dependancy rule, xcode will automatically fill the latest Trustylib release version number i.e. `1.2.6`
3. Click on `Add package` button. Xcode will clone the Trustylib git repository and attach to the xcode project, it should look like this,
4. Great! The library is now added to the xcode project and is all good for use.
#### *Cocoapods*
You need to install Cocoapods first, if not already installed. Cocoapods [usase guides](https://guides.cocoapods.org/using/using-cocoapods.html) 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!
## 2. Configuration ##
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,
## 3. Adding Trustylib UI widgets
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,
```swift
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
context: .trustMark
)
```
These lines of code create the Shop Grade widget,
```swift
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .shopGrade
)
```
The Buyer Protection widget can be created with these lines of code,
```swift
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .buyerProtection
)
```
This is how, Product Grade widget is added,
```swift
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](https://app.etrusted.com/) 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,
## 4. Display Trustmark widget ##
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,
#### *Swift with SwiftUI*
Trustylib widgets are created using SwiftUI, hence its pretty straight forward to use them in SwiftUI projects.
```swift
import Trustylib
import SwiftUI
struct ContentView: View {
var body: some View {
VStack {
Spacer()
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
context: .trustMark
)
.frame(height: 75)
}
.padding()
}
}
```
#### *Swift with UIKit*
Trustylib widgets are created using SwiftUI framework, therefore we need to wrap the Trustbadge widget with [UIHostingController](https://developer.apple.com/documentation/swiftui/uihostingcontroller) so that the widget could be added to the views created with UIKit framework. Here is how it is done,
```swift
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)
])
}
}
```
#### *Objective-C with UIKit*
Trustylib library has [TrustbadgeViewWrapper](https://github.com/trustedshops-public/etrusted-ios-trustbadge-library/blob/main/Sources/Trustylib/Views/TrustbadgeViewWrapper.swift) for adding Trustbadge views to Objective-C code. Below code shows, how it is done,
```objective-c
#import "RootViewControllerObjectiveC.h"
#import
@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;
}
@end
```
## 5. Display Shop Grade widget ##
To display the Shop Grade widget, you just need to pass `shopGrade` context and a valid channel id to the TrustbadgeView in above code examples.
#### *Swift with SwiftUI*
```swift
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .shopGrade
)
.frame(height: 75)
```
#### *Swift with UIKit*
```swift
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)
])
}
```
#### *Objective-C with UIKit*
```objective-c
UIViewController *trustbadgeViewController = [
TrustbadgeViewWrapper
createTrustbadgeViewWithTsId:@"X330A2E7D449E31E467D2F53A55DDD070"
channelId:@"chl-b309535d-baa0-40df-a977-0b375379a3cc"
context: TrustbadgeContextShopGrade
];
[self addChildViewController: trustbadgeViewController];
[self.view addSubview: trustbadgeViewController.view];
```
## 6. Display Buyer Protection widget ##
To display the Buyer Protection widget, you just need to pass `buyerProtection` context to the TrustbadgeView in above code examples.
#### *Swift with SwiftUI*
```swift
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
context: .buyerProtection
)
.frame(height: 75)
```
#### *Swift with UIKit*
```swift
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)
])
}
```
#### *Objective-C with UIKit*
```objective-c
UIViewController *trustbadgeViewController = [
TrustbadgeViewWrapper
createTrustbadgeViewWithTsId:@"X330A2E7D449E31E467D2F53A55DDD070"
channelId:@"chl-b309535d-baa0-40df-a977-0b375379a3cc"
context: TrustbadgeContextBuyerProtection
];
[self addChildViewController: trustbadgeViewController];
[self.view addSubview: trustbadgeViewController.view];
```
## 7. Display Product Grade widget ##
This is how, Product Grade widget can be added depending on the iOS technologies stack being used for the app,
#### *Swift with SwiftUI*
```swift
TrustbadgeView(
tsId: "X330A2E7D449E31E467D2F53A55DDD070",
channelId: "chl-c0ad29ff-a086-4191-a663-82fed64f6f65",
productId: "31303033",
context: .productGrade
)
.frame(height: 75)
```
#### *Swift with UIKit*
```swift
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)
])
}
```
#### *Objective-C with UIKit*
```objective-c
UIViewController *trustbadgeViewController = [
TrustbadgeViewWrapper
createTrustbadgeViewWithTsId:@"X330A2E7D449E31E467D2F53A55DDD070"
channelId:@"chl-c0ad29ff-a086-4191-a663-82fed64f6f65"
productId:@"31303033"
context: TrustbadgeContextProductGrade
];
[self addChildViewController: trustbadgeViewController];
[self.view addSubview: trustbadgeViewController.view];
```
## 8. Setting widget horizontal alignment ##
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,
```swift
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.
## 9. Dark mode support ##
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)
```xml
UIUserInterfaceStyle
Light/Dark
```
[UIUserInterfaceStyle](https://developer.apple.com/documentation/bundleresources/information_property_list/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.
## 10. Support ##
Please [let us know](https://github.com/trustedshops-public/etrusted-ios-trustbadge-library/issues) if you
have suggestions or questions. You may also contact Trusted Shop's mobile engineering team via email: [email protected]