Trusted shops library for the iOS platform

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 and Cocoapods.
Example projects 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.4
   
   
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 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.4 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 runtime environment variable Trustylib.Environment with supported values as development, stage and production. If this environment variable is found with one of the supported values, library environment is set accordingly. Else, library's environment is set to production as default environment.

This is how, you can set this runtime environment variable via your xcode project's scheme settings. More details could be found here.

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,

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,

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.

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 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)
        ])
    }
}

Objective-C with UIKit

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;
}

@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

TrustbadgeView(
   tsId: "X330A2E7D449E31E467D2F53A55DDD070",
   channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
   context: .shopGrade
)
.frame(height: 75)

Swift with UIKit

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

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

TrustbadgeView(
   tsId: "X330A2E7D449E31E467D2F53A55DDD070",
   channelId: "chl-b309535d-baa0-40df-a977-0b375379a3cc",
   context: .buyerProtection
)
.frame(height: 75)

Swift with UIKit

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

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

TrustbadgeView(
   tsId: "X330A2E7D449E31E467D2F53A55DDD070",
   channelId: "chl-c0ad29ff-a086-4191-a663-82fed64f6f65",
   productId: "31303033",
   context: .productGrade
)
.frame(height: 75)

Swift with UIKit

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

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,

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)

<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.

10. Support

Please let us know if you have suggestions or questions. You may also contact Trusted Shop's mobile engineering team via email: [email protected]