SmartLearn SDK for iOS

Introduction

The SmartLearn SDK(Due to renaming formerly known as EduRoomSDK. Project and cocoapod name is the old one as renaming takes a while) for iOS enables a third party app to be available in SmartLearn lessons.

The SmartLearn app works as a hub to link to third party apps and web content.

Supported languages: Swift and Objective-C.

How SmartLearn and your app work together

The SmartLearn app opens your app by making use of custom URL schemes. After successfully opening your app the SDK is kicking in and sends a heartbeat HTTPS request to the SmartLearn backend to signal that a student is active.

When teachers choose to include your app in their lessons, it will be displayed in the SmartLearn app. Upon tapping your app it will try to open it. If it is not installed on the device yet, the student is redirected to the app store to download it.

How to register

You can easily register your app at https://smart-learn.online/firmen/ios-sdk.

You need to define a few properties before registration though! Please read on for details.

We will review your submission and publish it as soon as possible.

Custom URL Scheme

Please choose a unique scheme to avoid collisions. Usually the bundle identifier is a good choice for a custom URL scheme, e.g. com.mycompany.myapp://

You register a custom URL scheme for your app by following Apple's official instructions.

App Store identifier

You can find your App Store identifier using the Apple's Link Maker. Search for your app and then inspect the direct link at the bottom. The identifier is the number after the string id.

Example: https://itunes.apple.com/de/app/eduroom-sch%C3%BCler-app/id1441459022?mt=8 the App Store identifier is: 1441459022.

If you don't have an identifier yet, you can register again or provide the missing id by sending an email to [email protected]. Please provide the name and custom url scheme of your app.

Installation & Examples

SmartLearn SDK is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'EduRoomSDK'

Please have a look at the example projects for Swift and Objective-C. In the AppDelegate.swift or AppDelegate.m files you can find a reference integration of the SDK.

To run the example project:

• Clone the repo git clone https://github.com/EdumodeOrg/EduRoomSDK-iOS.git
• CD to folder Example
• run pod install from the Example directory first.
• open EduRoomSDK.xcworkspace in XCode

Integrating the SDK

Everything is taking place in the AppDelegate class.

1. Import the the SmartLearn SDK

Swift

import EduRoomSDK

Objective-C

@import EduRoomSDK;

2. Start a session when your app is opened by SmartLearn

The main entry point is UIApplicationDelegate's application(_:open:options:) method.

application(_:didFinishLaunchingWithOptions:):

Swift

func application(_ app: UIApplication, open url: URL,
                 options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    
    if url.absoluteString.starts(with:"de.edumode.eduroomsdkexampleapp") {
        EduRoom.shared.startSession(url: url)
    }
    
    return true
}

Objective-C

- (BOOL)application:(UIApplication *)app
            openURL:(NSURL *)url
            options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
    if ([url.absoluteString hasPrefix:@"de.edumode.eduroomsdkexampleapp"]) {
	    [[EduRoom shared] startSessionWithUrl:url];
    }
    
    return YES;
}

Since iOS 13 Apple sets the options key .sourceApplication value to nil/null for apps not beling to your team. To prevent the SmartLearn SDK being

App resources used by the SDK

• The SDK sends a regular heartbeat ping HTTPS request to the SmartLearn backend. An ephemeral internal URL session is used to send the requests.

• The SDK will disable the app idle timer when a session starts. This is a precaution to keep the ping active while a student may not use the third party app for the length of a whole lesson. The timer is enabled again when a session stops.

How to test

Make sure the following steps have been completed:

• SDK integrated ✓
• Your App registered ✓

Simple custom URL scheme test

To test your custom URL scheme, you can create a single view iOS app. Invoke the following code to see if your app including the SmartLearn SDK is opened:

Swift

if let url = URL(string: "com.mycompany.myapp://test") {            
	UIApplication.shared.open(url, options: [:]) { (success) in
	     print(success)
	}
}

Objective-C

NSURL *url = [[NSURL alloc] initWithString:@"com.mycompany.myapp://test"];

[[UIApplication sharedApplication] openURL:url
                                   options:@{}
                         completionHandler:^(BOOL success) {
                                           NSLog(@"%d", success);
                                       }];

Full Integration Test

1. Install your app including the SmartLearn SDK on a device
2. Get the SmartLearn app from the App Store.
3. Create a teacher account at edumode.org. Scroll to Lehrer-App kostenlos ausprobieren. Follow the instructions in the email.
4. As student create an account in the SmartLearn app
5. As teacher create a group and invite the newly create student account with the provided QR code
6. As teacher create a ruleset. Search for your app and include it.
7. As teacher create a lesson. Set today's date and a broad time span. Set your newly created ruleset. Set your group. Click on Teilnehmerliste
8. As student you can pull to update available lessons or just wait a few seconds. As soon as the lesson appears tap it. Your app should appear. Tap it, a system dialog should popup asking you if you want to open the app. Upon accepting your app should open.
9. As teacher the student should turn green

If the student stays green for a longer than a few minutes the ping is working as expected.

Congratulations!

Recommendations

If possible show the status bar for every orientation. Experience shows that students check time of day several times per lesson. iOS will hide the status bar in landscape orientation and thus the clock. As some apps offer the best user experience when used in landscape orientation a student will pull down the message center to see the clock again not aware that this will result in backgrounding the app. This leads to potential missed out ping requests required to keep a student active in a lesson.

You can add a little obstacle to prevent pulling down on the status bar by overriding preferredScreenEdgesDeferringSystemGestures in your view controllers:

Swift

override var preferredScreenEdgesDeferringSystemGestures: UIRectEdge {
    get {
        return .all
    }
}

Objective-C

- (UIRectEdge)preferredScreenEdgesDeferringSystemGestures
{
    return UIRectEdgeAll;
}

Sadly, iPhone X models will always hide the status bar in lanscape orientation.

Bugs & Feedback

Please use project's Github Issues.

Author

Nicky Weber, [email protected]

License

SmartLearn SDK is available under the MIT license. See the LICENSE file for more info.